@tailor-platform/sdk-codemod 0.3.7 → 0.4.0-next.9

package/dist/index.js

@@ -5,14 +5,123 @@ import * as path from "pathe";
 import { readPackageJSON } from "pkg-types";
 import { arg, defineCommand, runMain } from "politty";
 import { z } from "zod";
-import { gte, lt, valid } from "semver";
+import { gte, lt, parse, valid } from "semver";
 import * as fs from "node:fs";
-import { glob } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { Lang, parse as parse$1 } from "@ast-grep/napi";
 import chalk from "chalk";
 import { structuredPatch } from "diff";
 import picomatch from "picomatch";
+import { execFileSync } from "node:child_process";
+//#region src/migration-doc.ts
+/**
+* Classify how much of a migration the codemod automates.
+* - `Automatic`: a transform fully covers it, with no residual to flag.
+* - `Partially automatic`: a transform covers the common cases but flags
+*   residuals (via `legacyPatterns`/`sourceStringLegacyPatterns`/
+*   `sourceTextLegacyPatterns`/`suspiciousPatterns`/
+*   `sourceStringSuspiciousPatterns`/`prompt`) to finish.
+* - `Manual`: no transform; the change is migrated by hand (optionally guided
+*   by a `prompt`). Whether a person or an LLM does it does not matter here.
+* @param codemod - The codemod registry entry
+* @returns The automation level
+*/
+function automationLevel(codemod) {
+	if (!codemod.scriptPath) return "Manual";
+	return (codemod.legacyPatterns?.length ?? 0) > 0 || (codemod.sourceStringLegacyPatterns?.length ?? 0) > 0 || (codemod.sourceTextLegacyPatterns?.length ?? 0) > 0 || (codemod.suspiciousPatterns?.length ?? 0) > 0 || (codemod.sourceStringSuspiciousPatterns?.length ?? 0) > 0 || codemod.prompt != null ? "Partially automatic" : "Automatic";
+}
+//#endregion
 //#region src/registry.ts
 const CODEMODS_ROOT = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), "codemods");
+const RENAME_BIN_SOURCE_VALUE_FLAGS = [
+	"--env-file-if-exists",
+	"--env-file",
+	"--profile",
+	"--config",
+	"--workspace-id",
+	"--arg",
+	"--query",
+	"--file",
+	"--name",
+	"--namespace",
+	"--dir",
+	"-e",
+	"-p",
+	"-c",
+	"-w",
+	"-a",
+	"-q",
+	"-f",
+	"-n"
+];
+const RENAME_BIN_SOURCE_COMMANDS = [
+	"api",
+	"apply",
+	"authconnection",
+	"completion",
+	"crash-report",
+	"crashreport",
+	"deploy",
+	"executor",
+	"function",
+	"generate",
+	"init",
+	"login",
+	"logout",
+	"machineuser",
+	"oauth2client",
+	"open",
+	"organization",
+	"profile",
+	"query",
+	"remove",
+	"secret",
+	"setup",
+	"show",
+	"skills",
+	"staticwebsite",
+	"tailordb",
+	"upgrade",
+	"user",
+	"workflow",
+	"workspace"
+];
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const RENAME_BIN_SOURCE_VALUE_GUARDS = RENAME_BIN_SOURCE_VALUE_FLAGS.flatMap((flag) => {
+	const escaped = escapeRegExp(flag);
+	return [`(?<!${escaped}\\s+)`, `(?<!${escaped}=)`];
+}).join("");
+const RENAME_BIN_SOURCE_COMMAND_OR_FLAG = `(?:--?[\\w-]+|${RENAME_BIN_SOURCE_COMMANDS.join("|")})`;
+const RENAME_BIN_SOURCE_COMMAND_TOKEN = "tailor-sdk(?:(?:\\.(?:cmd|ps1|exe))|(?:@[^\\s'\"`;|&)]+))?(?![\\w-])";
+const RENAME_BIN_SOURCE_LEGACY_PATTERN = new RegExp([
+	"(?<![.\\w-])",
+	"(?<![\"'])",
+	"(?<!\\\\[\"'])",
+	RENAME_BIN_SOURCE_VALUE_GUARDS,
+	RENAME_BIN_SOURCE_COMMAND_TOKEN,
+	`(?=\\s*(?:$|${RENAME_BIN_SOURCE_COMMAND_OR_FLAG}\\b))`
+].join(""));
+const RENAME_BIN_QUOTED_SOURCE_LEGACY_PATTERN = new RegExp([
+	"(?:^|[\\s;&|\\x00])(?:sh|bash|zsh)\\s+-\\w*c\\w*\\s+\\\\?[\"']",
+	RENAME_BIN_SOURCE_COMMAND_TOKEN,
+	`(?=\\s*(?:$|${RENAME_BIN_SOURCE_COMMAND_OR_FLAG}\\b))`
+].join(""));
+const RENAME_BIN_QUOTED_LEGACY_COMMAND_PATTERN = new RegExp([
+	RENAME_BIN_SOURCE_VALUE_GUARDS,
+	"[\"']",
+	RENAME_BIN_SOURCE_COMMAND_TOKEN,
+	"(?=\\s*(?:apply\\b|crash-report\\b|[^\"'`]*\\s--machineuser\\b))"
+].join(""));
+const V2_NEXT_1 = "2.0.0-next.1";
+const V2_NEXT_2 = "2.0.0-next.2";
+const V2_NEXT_4 = "2.0.0-next.4";
+const V2_NEXT_5 = "2.0.0-next.5";
+const V2_NEXT_6 = "2.0.0-next.6";
+const V2_NEXT_7 = "2.0.0-next.7";
+const V2_NEXT_9 = "2.0.0-next.9";
+/** All registered codemods, in registration order. */
 const allCodemods = [
 	{
 		id: "v2/define-generators-to-plugins",
@@ -20,8 +129,31 @@ const allCodemods = [
 		description: "Migrate defineGenerators() tuple syntax to definePlugins() with explicit plugin imports",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/define-generators-to-plugins/scripts/transform.js",
-		legacyPatterns: ["defineGenerators"]
+		legacyPatterns: ["defineGenerators"],
+		examples: [{
+			before: [
+				"import { defineGenerators } from \"@tailor-platform/sdk\";",
+				"",
+				"export const generators = defineGenerators(",
+				"  [\"@tailor-platform/kysely-type\", { distPath: \"db.ts\" }],",
+				");"
+			].join("\n"),
+			after: [
+				"import { definePlugins } from \"@tailor-platform/sdk\";",
+				"import { kyselyTypePlugin } from \"@tailor-platform/sdk/plugin/kysely-type\";",
+				"",
+				"export const generators = definePlugins(kyselyTypePlugin({ distPath: \"db.ts\" }));"
+			].join("\n")
+		}],
+		prompt: [
+			"defineGenerators() is replaced by definePlugins() in v2. The codemod rewrites the",
+			"known plugin tuples (kysely-type, enum-constants, file-utils, seed). For any",
+			"remaining defineGenerators([...]) the codemod left in place — a plugin it does not",
+			"know, or a non-tuple/spread form — convert it to definePlugins(pluginFn(config)),",
+			"importing the matching plugin from its @tailor-platform/sdk/plugin/<name> subpath."
+		].join("\n")
 	},
 	{
 		id: "v2/plugin-cli-import",
@@ -29,92 +161,1066 @@ const allCodemods = [
 		description: "Rewrite deprecated plugin re-export imports (kyselyTypePlugin, enumConstantsPlugin, fileUtilsPlugin, seedPlugin) from `@tailor-platform/sdk/cli` to their dedicated plugin subpaths",
 		since: "1.0.0",
 		until: "2.0.0",
-		scriptPath: "v2/plugin-cli-import/scripts/transform.js"
+		prereleaseUntil: V2_NEXT_1,
+		scriptPath: "v2/plugin-cli-import/scripts/transform.js",
+		examples: [{
+			before: "import { kyselyTypePlugin } from \"@tailor-platform/sdk/cli\";",
+			after: "import { kyselyTypePlugin } from \"@tailor-platform/sdk/plugin/kysely-type\";"
+		}]
 	},
 	{
 		id: "v2/test-run-arg-input",
 		name: "function test-run --arg input unwrap",
-		description: "Strip the deprecated {input: ...} wrapper from `tailor-sdk function test-run --arg` JSON in scripts and docs",
+		description: "Strip the deprecated {input: ...} wrapper from `tailor function test-run --arg` JSON in scripts and docs",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/test-run-arg-input/scripts/transform.js",
 		filePatterns: [
 			"**/package.json",
 			"**/*.{sh,bash,zsh}",
 			"**/*.md"
-		]
+		],
+		examples: [{
+			lang: "sh",
+			before: "tailor function test-run resolvers/add.ts --arg '{\"input\":{\"a\":1}}'",
+			after: "tailor function test-run resolvers/add.ts --arg '{\"a\":1}'"
+		}]
 	},
 	{
 		id: "v2/sdk-skills-shim",
-		name: "tailor-sdk-skills → tailor-sdk skills install",
-		description: "Replace deprecated `tailor-sdk-skills` invocations with `tailor-sdk skills install`",
+		name: "tailor-sdk-skills → tailor skills add",
+		description: "Replace deprecated `tailor-sdk-skills` invocations with `tailor skills add`",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/sdk-skills-shim/scripts/transform.js",
 		filePatterns: [
 			"**/package.json",
 			"**/*.{sh,bash,zsh,yml,yaml}",
 			"**/*.md"
 		],
-		legacyPatterns: ["tailor-sdk-skills"]
+		legacyPatterns: ["tailor-sdk-skills"],
+		examples: [{
+			lang: "sh",
+			before: "npx tailor-sdk-skills",
+			after: "tailor skills add"
+		}],
+		prompt: [
+			"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 skills add`."
+		].join("\n")
 	},
 	{
 		id: "v2/principal-unify",
-		name: "Unify TailorUser/TailorActor/TailorInvoker → TailorPrincipal",
-		description: "Rename TailorUser/TailorActor/TailorInvoker to TailorPrincipal, drop unauthenticatedTailorUser, and rename resolver body `user` to `caller`",
+		name: "Unify TailorUser/TailorActor/TailorActorType/TailorInvoker → TailorPrincipal",
+		description: "Rename TailorUser/TailorActor/TailorActorType/TailorInvoker to TailorPrincipal, drop unauthenticatedTailorUser, rename resolver body `user` to `caller`, and rename TailorDB callback `user` to `invoker`",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_2,
 		scriptPath: "v2/principal-unify/scripts/transform.js",
 		legacyPatterns: [
 			"TailorUser",
 			"TailorActor",
+			"TailorActorType",
 			"TailorInvoker",
 			"unauthenticatedTailorUser"
-		]
+		],
+		suspiciousPatterns: [
+			"caller?.",
+			"context.user",
+			"context.invoker ?? context.user",
+			"ResolverContext"
+		],
+		examples: [{
+			caption: "Type references unify under `TailorPrincipal`:",
+			before: "import type { TailorUser } from \"@tailor-platform/sdk\";",
+			after: "import type { TailorPrincipal } from \"@tailor-platform/sdk\";"
+		}, {
+			caption: "The resolver body `user` becomes `caller`:",
+			before: "body: ({ input, user }) => user.id,",
+			after: "body: ({ input, caller }) => caller.id,"
+		}],
+		prompt: [
+			"Finish the cases the codemod left for manual migration:",
+			"- Rename user -> caller in resolver bodies the codemod skipped because a `caller`",
+			"  binding already exists or renaming would shadow/collide with another value.",
+			"- Replace member-access on the removed unauthenticatedTailorUser (e.g.",
+			"  unauthenticatedTailorUser.id); the codemod only replaced standalone references",
+			"  with null and left member access to surface a type error.",
+			"- Review helper adapters that still accept or read `context.user`; v2 resolver",
+			"  context uses nullable `caller` and `invoker`, so project-specific helper",
+			"  semantics for anonymous callers and command invokers must be chosen explicitly.",
+			"- Review `caller?.` values passed to APIs that require non-null values. If the",
+			"  resolver requires authentication, throw or otherwise narrow before the call;",
+			"  if anonymous callers are allowed, keep the nullable flow explicit.",
+			"Use TailorPrincipal for the unified user/actor/invoker type."
+		].join("\n")
+	},
+	{
+		id: "v2/auth-attributes-rename",
+		name: "AttributeMap → Attributes",
+		description: "Rename auth attribute module augmentation and related SDK type names from `AttributeMap` to `Attributes`",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/auth-attributes-rename/scripts/transform.js",
+		legacyPatterns: [
+			"AttributeMap",
+			"interface AttributeMap",
+			"UserAttributeMap",
+			"InferredAttributeMap"
+		],
+		examples: [{
+			caption: "Module augmentation uses `Attributes`:",
+			before: "declare module \"@tailor-platform/sdk\" {\n  interface AttributeMap {\n    role: string;\n  }\n}",
+			after: "declare module \"@tailor-platform/sdk\" {\n  interface Attributes {\n    role: string;\n  }\n}"
+		}],
+		prompt: [
+			"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."
+		].join("\n")
 	},
 	{
 		id: "v2/apply-to-deploy",
 		name: "tailor-sdk apply → tailor-sdk deploy",
-		description: "Rewrite `tailor-sdk apply` invocations in package.json scripts, shell scripts, CI configs, and docs to the v2-recommended `tailor-sdk deploy` alias",
+		description: "Rewrite `tailor-sdk apply` invocations in package.json scripts, shell scripts, CI configs, and docs to the canonical v2 `tailor-sdk deploy` command",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/apply-to-deploy/scripts/transform.js",
 		filePatterns: [
 			"**/package.json",
 			"**/*.{sh,bash,zsh,yml,yaml}",
+			"**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
 			"**/*.md"
-		]
+		],
+		examples: [{
+			lang: "sh",
+			before: "tailor-sdk apply --profile prod",
+			after: "tailor-sdk deploy --profile prod"
+		}]
 	},
 	{
 		id: "v2/cli-rename",
-		name: "v2 CLI rename (single-word commands)",
-		description: "Rewrite `tailor-sdk crash-report` invocations to the v2 single-word `tailor-sdk crashreport` form across package.json scripts, shell scripts, CI configs, and docs",
+		name: "v2 CLI rename",
+		description: "Rewrite `tailor-sdk crash-report` to `tailor-sdk crashreport` and `--machineuser` to `--machine-user` across package.json scripts, shell scripts, CI configs, and docs",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/cli-rename/scripts/transform.js",
 		filePatterns: [
 			"**/package.json",
 			"**/*.{sh,bash,zsh,yml,yaml}",
 			"**/*.md"
-		]
+		],
+		legacyPatterns: ["tailor-sdk crash-report", "--machineuser"],
+		examples: [{
+			lang: "sh",
+			before: "tailor-sdk crash-report list\ntailor-sdk login --machineuser",
+			after: "tailor-sdk crashreport list\ntailor-sdk login --machine-user"
+		}],
+		prompt: [
+			"Apply the v2 CLI renames the codemod did not reach (only `tailor-sdk`-prefixed",
+			"invocations are rewritten): `tailor-sdk crash-report` -> `tailor-sdk crashreport`",
+			"and the `--machineuser` option -> `--machine-user`. Leave unrelated commands that",
+			"happen to use `--machineuser` alone."
+		].join("\n")
 	},
 	{
-		id: "v2/auth-invoker-unwrap",
+		id: "v2/env-var-rename",
+		name: "SDK environment variable rename",
+		description: "Rewrite unambiguous removed SDK environment variable names to their v2 `TAILOR_*` names and flag generic names for manual review",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/env-var-rename/scripts/transform.js",
+		filePatterns: [
+			"**/package.json",
+			"**/.env",
+			"**/.env.*",
+			"**/*.{env,sh,bash,zsh,yml,yaml,json,md}",
+			"**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"
+		],
+		legacyPatterns: [
+			"TAILOR_PLATFORM_SDK_CONFIG_PATH",
+			"TAILOR_PLATFORM_SDK_DTS_PATH",
+			"TAILOR_PLATFORM_SDK_ALLOW_CI_ID_INJECTION",
+			"TAILOR_PLATFORM_SDK_BUILD_ONLY",
+			"TAILOR_SDK_OUTPUT_DIR",
+			"TAILOR_SDK_SKILLS_SOURCE",
+			"TAILOR_SDK_VERSION",
+			"PLATFORM_URL",
+			"PLATFORM_OAUTH2_CLIENT_ID",
+			"TAILOR_ENABLE_INLINE_SOURCEMAP",
+			"TAILOR_PLATFORM_QUERY_NEWLINE_ON_ENTER",
+			"LOG_LEVEL",
+			"TAILOR_TOKEN"
+		],
+		sourceStringLegacyPatterns: [
+			"PLATFORM_URL",
+			"PLATFORM_OAUTH2_CLIENT_ID",
+			"LOG_LEVEL"
+		],
+		examples: [{
+			lang: "sh",
+			before: "TAILOR_PLATFORM_SDK_BUILD_ONLY=true tailor-sdk deploy",
+			after: "TAILOR_DEPLOY_BUILD_ONLY=true tailor-sdk deploy"
+		}, {
+			before: "const token = process.env.TAILOR_TOKEN;",
+			after: "const token = process.env.TAILOR_PLATFORM_TOKEN;"
+		}],
+		prompt: [
+			"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."
+		].join("\n")
+	},
+	{
+		id: "v2/auth-invoker-call-unwrap",
 		name: "auth.invoker(\"name\") → \"name\"",
-		description: "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.",
+		description: "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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
+		scriptPath: "v2/auth-invoker-call-unwrap/scripts/transform.js",
+		suspiciousPatterns: ["auth.invoker"],
+		reviewSupersededBy: ["v2/auth-invoker-unwrap"],
+		prompt: [
+			"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."
+		].join("\n"),
+		examples: [{
+			before: "createResolver({ authInvoker: auth.invoker(\"manager\") });",
+			after: "createResolver({ authInvoker: \"manager\" });"
+		}]
+	},
+	{
+		id: "v2/auth-invoker-unwrap",
+		name: "auth.invoker(\"name\") → invoker: \"name\"",
+		description: "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 `.start()` 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.",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_2,
 		scriptPath: "v2/auth-invoker-unwrap/scripts/transform.js",
-		legacyPatterns: ["auth.invoker"]
+		suspiciousPatterns: [
+			"auth.invoker",
+			"authInvoker:",
+			"authInvoker :",
+			"authInvoker?",
+			"{ authInvoker",
+			", authInvoker",
+			"\n  authInvoker",
+			"\n    authInvoker",
+			"\n      authInvoker",
+			"\"authInvoker\":",
+			"\"authInvoker\" :",
+			"\"authInvoker\"?",
+			"'authInvoker':",
+			"'authInvoker' :",
+			"'authInvoker'?"
+		],
+		prompt: [
+			"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 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> 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.start(), or startWorkflow() options. Keep platform/runtime",
+			"   payload keys such as tailor.workflow.startWorkflow(..., { 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 the SDK option rename and auth.invoker() removal."
+		].join("\n"),
+		examples: [{
+			before: "createResolver({ invoker: auth.invoker(\"manager\") });",
+			after: "createResolver({ invoker: \"manager\" });"
+		}]
+	},
+	{
+		id: "v2/auth-connection-token-helper",
+		name: "auth.getConnectionToken() → runtime authconnection",
+		description: "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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_2,
+		scriptPath: "v2/auth-connection-token-helper/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		examples: [{
+			before: "import { auth } from \"../tailor.config\";\n\nconst token = await auth.getConnectionToken(\"google\");",
+			after: "import { authconnection } from \"@tailor-platform/sdk/runtime\";\n\nconst token = await authconnection.getConnectionToken(\"google\");"
+		}],
+		prompt: [
+			"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."
+		].join("\n")
+	},
+	{
+		id: "v2/runtime-subpath-namespace",
+		name: "Runtime subpath imports use namespace objects",
+		description: "Rewrite `@tailor-platform/sdk/runtime/*` namespace-star and flat value imports to self-named namespace imports, and aggregate `file.deleteFile` calls to `file.delete`. `TailorContextAPI` and `TailorWorkflowAPI` now describe SDK wrappers; direct platform globals use `PlatformContextAPI` and `PlatformWorkflowAPI`.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_4,
+		scriptPath: "v2/runtime-subpath-namespace/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		legacyPatterns: [
+			"@tailor-platform/sdk/runtime/iconv",
+			"@tailor-platform/sdk/runtime/secretmanager",
+			"@tailor-platform/sdk/runtime/authconnection",
+			"@tailor-platform/sdk/runtime/idp",
+			"@tailor-platform/sdk/runtime/workflow",
+			"@tailor-platform/sdk/runtime/context",
+			"@tailor-platform/sdk/runtime/file",
+			"@tailor-platform/sdk/runtime/aigateway"
+		],
+		examples: [
+			{
+				before: "import * as iconv from \"@tailor-platform/sdk/runtime/iconv\";\niconv.convert(value, \"UTF-8\", \"Shift_JIS\");",
+				after: "import { iconv } from \"@tailor-platform/sdk/runtime/iconv\";\niconv.convert(value, \"UTF-8\", \"Shift_JIS\");"
+			},
+			{
+				before: "import { get } from \"@tailor-platform/sdk/runtime/aigateway\";\nconst gateway = await get(\"main\");",
+				after: "import { aigateway } from \"@tailor-platform/sdk/runtime/aigateway\";\nconst gateway = await aigateway.get(\"main\");"
+			},
+			{
+				before: "import { file } from \"@tailor-platform/sdk/runtime\";\nawait file.deleteFile(\"ns\", \"Doc\", \"blob\", \"record-id\");",
+				after: "import { file } from \"@tailor-platform/sdk/runtime\";\nawait file.delete(\"ns\", \"Doc\", \"blob\", \"record-id\");"
+			}
+		],
+		prompt: [
+			"In Tailor SDK v2, runtime subpath modules export only a self-named namespace",
+			"object (for example, `iconv` from `@tailor-platform/sdk/runtime/iconv`).",
+			"Default and flat value imports such as",
+			"`import { get } from \"@tailor-platform/sdk/runtime/aigateway\"` are removed.",
+			"The codemod rewrites straightforward namespace-star imports and flat named value",
+			"imports. It also rewrites direct `file.deleteFile` calls on the aggregate runtime",
+			"namespace to `file.delete`. Destructured aggregate `deleteFile` references require",
+			"manual migration. Review any remaining runtime imports manually, especially when",
+			"a local binding or nested scope shadows an imported value, or when",
+			"type-position namespace member references need explicit top-level type imports.",
+			"For direct platform globals, replace `TailorContextAPI` and `TailorWorkflowAPI`",
+			"type references with `PlatformContextAPI` and `PlatformWorkflowAPI` respectively."
+		].join("\n")
 	},
 	{
 		id: "v2/tailordb-namespace",
 		name: "Tailordb → tailordb (lowercase ambient namespace)",
-		description: "Rewrite references to the deprecated capital-cased `Tailordb` ambient namespace (`Tailordb.QueryResult`, `Tailordb.CommandType`, `Tailordb.Client`, `typeof Tailordb.Client`) to the new lowercase `tailordb.*` namespace re-published by the SDK in place of `@tailor-platform/function-types`.",
+		description: "Rewrite references to the removed capital-cased `Tailordb` ambient namespace (`Tailordb.QueryResult`, `Tailordb.CommandType`, `Tailordb.Client`, `typeof Tailordb.Client`) to the lowercase `tailordb.*` namespace exposed by `@tailor-platform/sdk/runtime/globals`. Because v2 no longer activates ambient declarations automatically, each file that contains `tailordb.*` references after the rewrite must also add `import \"@tailor-platform/sdk/runtime/globals\"`.",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/tailordb-namespace/scripts/transform.js",
-		legacyPatterns: ["Tailordb."]
+		legacyPatterns: ["Tailordb."],
+		examples: [{
+			before: "const command: Tailordb.CommandType = \"SELECT\";",
+			after: "import \"@tailor-platform/sdk/runtime/globals\";\nconst command: tailordb.CommandType = \"SELECT\";"
+		}],
+		prompt: [
+			"The capital-cased Tailordb ambient namespace is removed in v2; use the lowercase",
+			"tailordb.* namespace from @tailor-platform/sdk/runtime/globals. The codemod rewrites",
+			"the known members (QueryResult, CommandType, Client). Rewrite any other remaining",
+			"Tailordb.* reference to its tailordb.* equivalent (and confirm the member still",
+			"exists on the lowercase namespace).",
+			"Also add `import \"@tailor-platform/sdk/runtime/globals\"` at the top of each file",
+			"that contains any tailordb.* type reference — v2 no longer activates ambient",
+			"declarations automatically on SDK import."
+		].join("\n")
+	},
+	{
+		id: "v2/db-type-to-table",
+		name: "db.type() → db.table()",
+		description: "Rename TailorDB schema builder calls from `db.type()` to `db.table()`. TailorDB schema definitions now use table terminology in SDK projects.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_4,
+		scriptPath: "v2/db-type-to-table/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		legacyPatterns: ["db.type"],
+		examples: [{
+			before: "import { db } from \"@tailor-platform/sdk\";\n\nexport const user = db.type(\"User\", {\n  name: db.string(),\n});",
+			after: "import { db } from \"@tailor-platform/sdk\";\n\nexport const user = db.table(\"User\", {\n  name: db.string(),\n});"
+		}],
+		prompt: [
+			"In Tailor SDK v2, TailorDB schema definitions use db.table(...) instead of",
+			"db.type(...). The codemod rewrites member accesses on db imported from",
+			"@tailor-platform/sdk, including aliases such as `import { db as schema }`.",
+			"It flags destructured builder aliases such as `const { type } = db` and",
+			"local builder aliases such as `const schema = db`, `schema = db`, or",
+			"`function make(schema = db) { ... }` for manual review because the local",
+			"alias may require call-site renaming.",
+			"Review any remaining db.type references and rename SDK TailorDB schema builder",
+			"calls to db.table. Leave unrelated local objects with a .type() method unchanged."
+		].join("\n")
+	},
+	{
+		id: "v2/forward-relation-name",
+		name: "TailorDB forward relation names derive from field names",
+		description: "Review TailorDB relations that omit `toward.as`. Their forward GraphQL field names now derive from the relation field name with a trailing `ID`, `Id`, or `id` removed, instead of from the target table name.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_5,
+		scriptPath: "v2/forward-relation-name/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		suspiciousPatterns: [
+			/\.relation\b(?!\s*\()/,
+			/\{[^}\n]*\brelation\b[^}\n]*\}\s*=/,
+			/\[\s*["']relation["']\s*\]/
+		],
+		examples: [{
+			caption: "Preserve the v1 GraphQL field name by making it explicit:",
+			before: [
+				"ownerId: db.uuid().relation({",
+				"  type: \"n-1\",",
+				"  toward: { type: user },",
+				"}),"
+			].join("\n"),
+			after: [
+				"ownerId: db.uuid().relation({",
+				"  type: \"n-1\",",
+				"  toward: { type: user, as: \"user\" },",
+				"}),"
+			].join("\n")
+		}],
+		prompt: [
+			"Tailor SDK v2 derives a default forward GraphQL relation name from the source",
+			"field name by removing a trailing ID, Id, or id. V1 derived it from the target",
+			"table name. Review each reported non-self relation that omits toward.as.",
+			"",
+			"If consumers must keep using the v1 GraphQL field name, inspect the v1 schema and",
+			"copy that exact field name into toward.as. Otherwise, update GraphQL operations",
+			"and consumer code to use the new field-based name. No change is needed when the old",
+			"and new names are identical. Relations with a guaranteed non-empty toward.as,",
+			"self-relations, and keyOnly relations are unchanged. For an empty or dynamic",
+			"toward.as, determine whether its runtime value can be falsy; if so, treat the",
+			"relation as using the default name.",
+			"",
+			"A relation field without a trailing ID, Id, or id would default to its own scalar",
+			"field name and therefore conflict. Give that relation an explicit toward.as."
+		].join("\n")
+	},
+	{
+		id: "v2/execute-script-arg",
+		name: "executeScript arg JSON.stringify → value",
+		description: "Unwrap `JSON.stringify(...)` passed as the `executeScript` `arg` option. In v2 `arg` takes a JSON-serializable value and is serialized internally, so a pre-stringified argument double-encodes.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_2,
+		scriptPath: "v2/execute-script-arg/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,mjs,cjs,js}"],
+		suspiciousPatterns: [[
+			"executeScript",
+			"JSON.stringify",
+			/\barg\s*[:=]|["']arg["']\s*(?::|\]\s*[:=])/
+		]],
+		prompt: [
+			"In Tailor SDK v2 the executeScript() arg option takes a JSON-serializable value",
+			"and is serialized internally, so a pre-stringified argument double-encodes. The",
+			"codemod already rewrote the direct form arg: JSON.stringify(X) to arg: X. Review",
+			"the executeScript calls in these files for cases it could not rewrite — where the",
+			"arg value is reached indirectly, for example:",
+			"- a variable holding a JSON.stringify(...) result (const s = JSON.stringify(x); ... arg: s)",
+			"- JSON.stringify(x, null, 2) or another multi-argument form",
+			"- an options object built or spread dynamically",
+			"",
+			"For each such call, pass the underlying value directly as arg (drop the",
+			"JSON.stringify wrapper) so executeScript serializes it once. Leave calls that",
+			"already pass a plain value unchanged."
+		].join("\n"),
+		examples: [{
+			before: "await executeScript({ ...opts, arg: JSON.stringify({ a: 1 }) });",
+			after: "await executeScript({ ...opts, arg: { a: 1 } });"
+		}]
+	},
+	{
+		id: "v2/wait-point-rename",
+		name: "defineWaitPoint/defineWaitPoints → createWaitPoint/createWaitPoints",
+		description: "Rename `defineWaitPoint` and `defineWaitPoints` to `createWaitPoint` and `createWaitPoints`. The functions create runtime instances with `.wait()` / `.resolve()` methods, so the `create*` prefix is used consistently.",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/wait-point-rename/scripts/transform.js",
+		legacyPatterns: ["defineWaitPoint", "defineWaitPoints"],
+		examples: [{
+			before: "import { defineWaitPoints } from \"@tailor-platform/sdk\";\n\nexport const { approval } = defineWaitPoints((define) => ({\n  approval: define<{ message: string }, { approved: boolean }>(),\n}));",
+			after: "import { createWaitPoints } from \"@tailor-platform/sdk\";\n\nexport const { approval } = createWaitPoints((define) => ({\n  approval: define<{ message: string }, { approved: boolean }>(),\n}));"
+		}]
+	},
+	{
+		id: "v2/workflow-trigger-rename",
+		name: "workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow → startWorkflow/startJobFunction/resumeWorkflowExecution",
+		description: "Rename tailor.workflow call sites from the pre-alignment triggerWorkflow/triggerJobFunction/resumeWorkflow names to the canonical startWorkflow/startJobFunction/resumeWorkflowExecution names, on both the ambient tailor.workflow global and a workflow value imported from @tailor-platform/sdk/runtime(/workflow). For a renamed triggerWorkflow call, also renames a literal `invoker` option key to `authInvoker` — startWorkflow's options expect the platform shape directly, unlike the removed triggerWorkflow wrapper, which converted invoker to authInvoker internally.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_6,
+		scriptPath: "v2/workflow-trigger-rename/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		legacyPatterns: [
+			"triggerWorkflow",
+			"triggerJobFunction",
+			"resumeWorkflow"
+		],
+		examples: [{
+			before: "import { workflow } from \"@tailor-platform/sdk/runtime\";\n\nawait workflow.triggerWorkflow(\"myWorkflow\", { data: \"value\" });",
+			after: "import { workflow } from \"@tailor-platform/sdk/runtime\";\n\nawait workflow.startWorkflow(\"myWorkflow\", { data: \"value\" });"
+		}, {
+			caption: "A literal invoker option is renamed to authInvoker:",
+			before: "await workflow.triggerWorkflow(\"myWorkflow\", { data: \"value\" }, { invoker: myInvoker });",
+			after: "await workflow.startWorkflow(\"myWorkflow\", { data: \"value\" }, { authInvoker: myInvoker });"
+		}],
+		prompt: [
+			"The pre-alignment tailor.workflow names triggerWorkflow, triggerJobFunction, and",
+			"resumeWorkflow are removed from the SDK's type surface in v2; use the canonical",
+			"startWorkflow, startJobFunction, and resumeWorkflowExecution names instead. The",
+			"codemod rewrites direct member-access call sites on the ambient tailor.workflow",
+			"global and on a workflow value imported from @tailor-platform/sdk/runtime or",
+			"@tailor-platform/sdk/runtime/workflow (including aliased imports). It skips a",
+			"file entirely when a local declaration shadows the workflow import or the",
+			"ambient tailor name, to avoid rewriting an unrelated same-named value — review",
+			"those manually.",
+			"",
+			"For a renamed triggerWorkflow call, the codemod also renames a literal invoker",
+			"option key (including shorthand { invoker }) to authInvoker, since startWorkflow",
+			"expects the platform's authInvoker shape directly while triggerWorkflow's removed",
+			"wrapper converted invoker to authInvoker internally.",
+			"",
+			"Also review, and migrate by hand:",
+			"- Destructured references (e.g. const { triggerWorkflow } = workflow) — the",
+			"  codemod only rewrites direct member-access calls.",
+			"- Imported TriggerWorkflowOptions / TriggerJobFunctionOptions types — rename",
+			"  them to StartWorkflowOptions / StartJobFunctionOptions.",
+			"- An invoker option passed via a variable or spread (not a literal object) —",
+			"  the codemod only inspects literal object arguments; rename the invoker key",
+			"  to authInvoker in the options object's own definition."
+		].join("\n")
+	},
+	{
+		id: "v2/open-download-stream",
+		name: "openDownloadStream → downloadStream",
+		description: "The deprecated `openDownloadStream` file-streaming API is removed in v2. Use `downloadStream` for streamed file downloads. The generated file utilities now emit `downloadFileStream` (which calls `downloadStream` and returns `FileDownloadStreamResponse`) instead of the removed `openFileDownloadStream` helper.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_2,
+		filePatterns: ["**/*.{ts,tsx,mts,cts,mjs,cjs,js}"],
+		suspiciousPatterns: ["openDownloadStream", "openFileDownloadStream"],
+		examples: [{
+			before: "const res = await openDownloadStream(namespace, typeName, fieldName, recordId);",
+			after: "const res = await downloadStream(namespace, typeName, fieldName, recordId);"
+		}],
+		prompt: [
+			"The openDownloadStream file-streaming API is removed in v2. Replace every call to",
+			"openDownloadStream with downloadStream (same arguments). If you used the generated",
+			"openFileDownloadStream helper, switch to downloadFileStream, which calls",
+			"downloadStream and returns FileDownloadStreamResponse."
+		].join("\n")
+	},
+	{
+		id: "v2/runtime-globals-opt-in",
+		name: "Ambient runtime globals are opt-in",
+		description: "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.)",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
+		scriptPath: "v2/runtime-globals-opt-in/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		suspiciousPatterns: [
+			"tailor.context",
+			"tailor.iconv",
+			"tailor.idp",
+			"tailor.secretmanager",
+			"tailor.authconnection",
+			"tailor.workflow",
+			"tailor[",
+			"tailordb.Client",
+			"tailordb.CommandType",
+			"tailordb.QueryResult",
+			"tailordb.file",
+			"tailordb[",
+			"TailorDBFileError",
+			"TailorErrorItem",
+			"TailorErrorMessage",
+			"TailorErrors"
+		],
+		sourceStringSuspiciousPatterns: [
+			"new tailor.idp.Client",
+			/[=(:,[]\s*tailor\.idp\.Client\b/,
+			/(?:(?:=>|[=(:,<{]|\[)\s*|\b(?:return|await|typeof)\s+)tailor\.(?:authconnection|context|iconv|idp|secretmanager|workflow)(?:\.[A-Za-z_$][\w$]*)?\b/,
+			/\btailor\.(?:authconnection|context|iconv|idp|secretmanager|workflow)\.[A-Za-z_$][\w$]*\s*\(/,
+			"tailor[",
+			/\btailordb\.file\.[A-Za-z_$][\w$]*\s*\(/,
+			/(?:(?:=>|[=(:,<{]|\[)\s*|\b(?:return|await|typeof)\s+)tailordb\.file\b/,
+			/(?:\bnew\s+|(?:=>|[=(:,<{]|\[)\s*|\b(?:return|await|typeof)\s+)tailordb\.(?:Client|CommandType|QueryResult)\b/,
+			/<\s*tailordb\.(?:Client|CommandType|QueryResult)\b/,
+			"tailordb[",
+			/(?:\bnew\s+|\bthrow\s+|\binstanceof\s+)Tailor(?:DBFileError|Errors|ErrorMessage)\b/,
+			/(?:[:=<]\s*|\bas\s+)Tailor(?:DBFileError|Errors|ErrorMessage|ErrorItem)\b/,
+			/[:<]\s*TailorErrorItem\b/
+		],
+		examples: [{
+			caption: "Preferred: switch to the typed wrappers from `@tailor-platform/sdk/runtime` and drop the ambient globals:",
+			before: "const client = new tailor.idp.Client();",
+			after: "import { idp } from \"@tailor-platform/sdk/runtime\";\nconst client = new idp.Client({ namespace: \"my-namespace\" });"
+		}, {
+			caption: "Fallback: only if you must keep referencing the bare `tailor.*` names, opt into the global declarations:",
+			before: "const client = new tailor.idp.Client();",
+			after: "import \"@tailor-platform/sdk/runtime/globals\";\nconst client = new tailor.idp.Client();"
+		}],
+		prompt: [
+			"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`. 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:",
+			"- per-file: `import \"@tailor-platform/sdk/runtime/globals\";`",
+			"- project-wide: `\"types\": [\"@tailor-platform/sdk/runtime/globals\"]` in",
+			"  the relevant tsconfig compilerOptions",
+			"",
+			"Leave files unchanged when the matching name is local, imported from another",
+			"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."
+		].join("\n")
+	},
+	{
+		id: "v2/workflow-trigger-dispatch",
+		name: "Workflow job start() and start tests",
+		description: "Workflow job `.start()` (previously `.trigger()`) now aligns with the platform runtime: it returns the job result directly instead of a Promise wrapper, and tests no longer run job bodies locally. Mock start responses with `mockWorkflow()` (`setJobHandler` / `enqueueResult`, assert via `startedJobs`), or use `runWorkflowLocally()` for a full-chain local run.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
+		suspiciousPatterns: [".trigger("],
+		examples: [{
+			caption: "Tests must mock the workflow runtime instead of running bodies locally:",
+			before: "const result = await orderJob.start({ id });\nexpect(result.status).toBe(\"done\");",
+			after: "using wf = mockWorkflow();\nwf.setJobHandler((jobName) => (jobName === \"order-job\" ? { status: \"done\" } : null));\nconst result = await orderJob.start({ id });\nexpect(result.status).toBe(\"done\");"
+		}],
+		prompt: [
+			"Workflow job .start() now uses the platform workflow runtime instead of running",
+			"the job body locally. In tests, acquire `using wf = mockWorkflow()` and provide",
+			"start responses (setJobHandler / enqueueResult), or use runWorkflowLocally() for a",
+			"full-chain local run; an unmocked start now throws. Outside tests, treat the",
+			"start result as the job output directly (no Promise wrapper to unwrap)."
+		].join("\n")
+	},
+	{
+		id: "v2/workflow-start-rename",
+		name: "Workflow.trigger()/WorkflowJob.trigger() → .start()",
+		description: "Rename `Workflow.trigger()` (returned by `createWorkflow()`) and `WorkflowJob.trigger()` (returned by `createWorkflowJob()`) to `.start()`, aligning the SDK's ergonomic verb with the platform's `start*` RPC vocabulary. No codemod ships for this rename: distinguishing a workflow/job `.trigger()` call from an unrelated object's own `.trigger()` method requires resolving the receiver back to a `createWorkflow`/`createWorkflowJob` result across files, which the SDK's own CLI bundler already does for build-time rewriting. Reusing that logic in a standalone script is a nontrivial lift, and — unlike the bundler, which fails loudly when it cannot rewrite a call — a codemod false positive would silently rewrite an unrelated `.trigger()` call with no error. For the call-site volume this rename typically involves, manual review guided by the prompt below is the safer trade-off.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_7,
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		suspiciousPatterns: [".trigger("],
+		examples: [{
+			before: ["const inventory = checkInventory.trigger({ orderId: input.orderId });", "const workflowRunId = await orderProcessingWorkflow.trigger(args, { invoker: \"manager\" });"].join("\n"),
+			after: ["const inventory = checkInventory.start({ orderId: input.orderId });", "const workflowRunId = await orderProcessingWorkflow.start(args, { invoker: \"manager\" });"].join("\n")
+		}],
+		prompt: [
+			"In Tailor SDK v2, the ergonomic .trigger() method on a createWorkflow() or",
+			"createWorkflowJob() result is renamed to .start(). This is unrelated to the",
+			"separate tailor.workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow removal",
+			"(see the workflow-trigger-rename codemod) — this rename targets the SDK's own",
+			"ergonomic wrapper, not the low-level platform call.",
+			"",
+			"For each flagged `.trigger(` call in these files:",
+			"1. Confirm the receiver is a workflow or job object — typically a local const",
+			"   assigned from createWorkflow(...)/createWorkflowJob(...), a named import of one,",
+			"   or the default import of a workflow module. Skip receivers that are unrelated",
+			"   objects with their own .trigger() method (state machines, event emitters, etc.).",
+			"2. Rename the call from .trigger(...) to .start(...); the argument list is unchanged.",
+			"3. Update any mock/test code that reads WorkflowJob['trigger'] / Workflow['trigger']",
+			"   as a type, or that mocks the ergonomic method via a wrapper — for example,",
+			"   `wf.job(definition)` / `wf.workflow(definition)` from mockWorkflow() now return a",
+			"   mock of the `.start` method.",
+			"4. Update prose/docs/comments that say \"trigger the workflow/job\" to \"start\" only",
+			"   where they describe this SDK verb specifically, not unrelated event terminology."
+		].join("\n")
+	},
+	{
+		id: "v2/cli-token-keyring-storage",
+		name: "CLI tokens stored in the OS keyring",
+		description: "CLI login tokens are stored in the OS keyring by default when available, falling back to the platform config file when it is not. No source change is required; re-login if you need tokens moved into the keyring.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_2,
+		notice: true
+	},
+	{
+		id: "v2/cli-users-by-subject",
+		name: "CLI users keyed by subject ID",
+		description: "The CLI stores human users by their stable subject ID instead of email (email is kept for display). Legacy email-keyed entries are migrated automatically on the next login or token refresh. No source change is required.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
+		notice: true
+	},
+	{
+		id: "v2/function-logs-content-hash",
+		name: "function logs require a content hash for source mapping",
+		description: "`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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
+		notice: true
+	},
+	{
+		id: "v2/rename-bin",
+		name: "tailor-sdk binary → tailor",
+		description: "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. If your CI workflows were generated by `tailor setup`, re-run `tailor setup` afterwards so they pin tailor-platform/actions v2 — the v1 actions invoke the removed `tailor-sdk` bin.",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/rename-bin/scripts/transform.js",
+		filePatterns: [
+			"**/package.json",
+			"**/*.{sh,bash,zsh,yml,yaml}",
+			"**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
+			"**/*.md"
+		],
+		legacyPatterns: ["tailor-sdk"],
+		sourceStringLegacyPatterns: [
+			RENAME_BIN_SOURCE_LEGACY_PATTERN,
+			RENAME_BIN_QUOTED_SOURCE_LEGACY_PATTERN,
+			RENAME_BIN_QUOTED_LEGACY_COMMAND_PATTERN
+		],
+		sourceTextLegacyPatterns: [
+			RENAME_BIN_SOURCE_LEGACY_PATTERN,
+			RENAME_BIN_QUOTED_SOURCE_LEGACY_PATTERN,
+			RENAME_BIN_QUOTED_LEGACY_COMMAND_PATTERN
+		],
+		examples: [{
+			lang: "sh",
+			before: "tailor-sdk deploy\nnpx tailor-sdk@latest login",
+			after: "tailor deploy\nnpx @tailor-platform/sdk@latest login"
+		}],
+		prompt: [
+			"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."
+		].join("\n")
+	},
+	{
+		id: "v2/tailor-output-ignore-dir",
+		name: ".tailor-sdk ignore entries → .tailor",
+		description: "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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/tailor-output-ignore-dir/scripts/transform.js",
+		filePatterns: [
+			"**/.gitignore",
+			"**/.npmignore",
+			"**/.dockerignore",
+			"**/gitignore",
+			"**/npmignore",
+			"**/dockerignore",
+			"**/_gitignore",
+			"**/_npmignore",
+			"**/_dockerignore",
+			"**/__dot__gitignore",
+			"**/__dot__npmignore",
+			"**/__dot__dockerignore",
+			"**/*.gitignore",
+			"**/*.npmignore",
+			"**/*.dockerignore"
+		],
+		examples: [{
+			lang: "gitignore",
+			before: ".tailor-sdk/",
+			after: ".tailor/"
+		}]
+	},
+	{
+		id: "v2/tailordb-validate-simplify",
+		name: "ValidateFn simplification and type-level validate",
+		description: "Field-level `ValidateFn` is simplified from `(args: { value, data, invoker }) => boolean` to `(args: { value }) => string | void` — the function now returns the error message directly instead of a separate `[fn, message]` tuple. The `ValidateConfig` tuple form and `Validators<F>` record syntax on `db.type().validate()` are removed. Type-level validation uses `db.type().validate((args, issues) => void)` with `{ newRecord, oldRecord, invoker }` args and an `issues(field, message)` callback for cross-field rules.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_5,
+		suspiciousPatterns: [
+			"ValidateConfig",
+			"Validators<",
+			"ValidatorsBase",
+			".validate("
+		],
+		examples: [{
+			caption: "Field-level validate: return an error message string instead of a boolean (tuple form removed):",
+			before: ".validate(\n  [({ value }) => value.length > 5, \"Name must be longer than 5 characters\"],\n)",
+			after: ".validate(({ value }) =>\n  value.length <= 5 ? \"Name must be longer than 5 characters\" : undefined,\n)"
+		}, {
+			caption: "Type-level validate: per-field record syntax replaced by a single function with `issues()` callback:",
+			before: ".validate({\n  name: [({ value }) => value.length > 5, \"Name must be longer than 5\"],\n})",
+			after: ".validate(({ newRecord }, issues) => {\n  if (newRecord.name && newRecord.name.length <= 5) {\n    issues(\"name\", \"Name must be longer than 5\");\n  }\n})"
+		}],
+		prompt: [
+			"The v2 SDK simplifies field validation and introduces type-level validation.",
+			"",
+			"Field-level `.validate()` changes:",
+			"- Signature: `(args: { value, data, invoker }) => boolean` → `(args: { value }) => string | void`",
+			"- The function now returns the error message string directly (or undefined/void to pass)",
+			"  instead of returning a boolean with the message in a separate tuple.",
+			"- The `[fn, errorMessage]` tuple form (`ValidateConfig`) is removed.",
+			"- `data` and `invoker` are no longer available in field-level validators.",
+			"  Use type-level `.validate()` for cross-field or invoker-dependent rules.",
+			"",
+			"Type-level `.validate()` on `db.type()` changes:",
+			"- Old: `.validate({ fieldName: fn | [fn, msg] | fn[] })` (per-field record, `Validators<F>` type)",
+			"- New: `.validate((args, issues) => void)` (single function, `TypeValidateFn<F>` type)",
+			"- Args: `{ newRecord, oldRecord, invoker }` — `newRecord` is the record after hooks run",
+			"- Call `issues(field, message)` to report validation errors; `field` supports dotted paths",
+			"- Move per-field validators that need `data`/`invoker` to the type-level function",
+			"",
+			"For each remaining `ValidateConfig`, `Validators<`, or old-signature `.validate()` usage:",
+			"1. Rewrite field-level validators to return the error string directly",
+			"2. Move cross-field / invoker-dependent validators to the type-level function",
+			"3. Remove unused `ValidateConfig` / `Validators` type imports"
+		].join("\n")
+	},
+	{
+		id: "v2/tailordb-hook-redesign",
+		name: "TailorDB hook redesign: field-level args and type-level hooks",
+		description: "Field-level `HookFn` args change from `{ value, data, invoker }` to create `{ input, invoker, now }` / update `{ input, oldValue, invoker, now }` — `value` is renamed to `input`, matching the `input` arg on type-level hooks (same pre-hook data, narrowed to one field); `data` (the full record) is removed; `oldValue` (previous field value) is added for update hooks only; `now` (operation timestamp) is shared across all hooks. Type-level hooks on `db.type().hooks()` change from per-field mapping `{ fieldName: { create, update } }` (`Hooks<F>`) to a single `{ create, update }` object (`TypeHook<F>`) — create hooks take `{ input, invoker, now }`, update hooks take `{ input, oldRecord, invoker, now }` (oldRecord is always non-null). Both return partial field overrides.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_5,
+		suspiciousPatterns: [
+			"Hooks<",
+			"HookFn<",
+			"Hook<",
+			".hooks("
+		],
+		examples: [{
+			caption: "Field-level hooks: `value` renamed to `input`, `data` replaced by `oldValue` and `now`; use `now` instead of `new Date()`:",
+			before: "db.datetime().hooks({\n  create: ({ value }) => value ?? new Date(),\n  update: () => new Date(),\n})",
+			after: "db.datetime().hooks({\n  create: ({ input, now }) => input ?? now,\n  update: ({ now }) => now,\n})"
+		}, {
+			caption: "Type-level hooks: per-field mapping replaced by single create/update functions:",
+			before: ".hooks({\n  fullAddress: {\n    create: ({ data }) => `${data.postalCode} ${data.address}`,\n    update: ({ data }) => `${data.postalCode} ${data.address}`,\n  },\n})",
+			after: ".hooks({\n  create: ({ input }) => ({\n    fullAddress: `${input.postalCode} ${input.address}`,\n  }),\n  update: ({ input }) => ({\n    fullAddress: `${input.postalCode} ${input.address}`,\n  }),\n})"
+		}],
+		prompt: [
+			"The v2 SDK redesigns TailorDB hooks at both field and type levels.",
+			"",
+			"Field-level `.hooks()` on individual fields:",
+			"- Create args: `{ value, data, invoker }` → `{ input, invoker, now }` (no `oldValue`)",
+			"- Update args: `{ value, data, invoker }` → `{ input, oldValue, invoker, now }`",
+			"- `value` is renamed to `input`, matching the type-level hook's `input` arg — both are",
+			"  the same pre-hook data, at different granularity",
+			"- `data` (full record) is removed; update hooks get `oldValue` (previous field value) instead",
+			"- `now` provides the operation timestamp — use `now` instead of `new Date()`",
+			"- If a field-level hook needs the full record (other fields), move it to a type-level hook",
+			"",
+			"Type-level `.hooks()` on `db.type()`:",
+			"- Old: `.hooks({ fieldName: { create: fn, update: fn } })` (per-field mapping, `Hooks<F>` type)",
+			"- New: `.hooks({ create: fn, update: fn })` (single object, `TypeHook<F>` type)",
+			"- Each function: `({ input, oldRecord, invoker, now }) => ({ fieldName: value, ... })`",
+			"- `input` is the pre-hook input (may have nullish values for optional/defaulted fields)",
+			"- Create hooks do not receive `oldRecord`; update hooks receive `oldRecord` (always non-null)",
+			"- Return an object with only the fields to override; unmentioned fields are unchanged",
+			"",
+			"Migration steps for each `.hooks()` call on a `db.type()`:",
+			"1. If the old per-field hooks only use `value`/`invoker` and don't reference `data`,",
+			"   convert them to field-level hooks with the new args (`value` → `input`, plus `oldValue`, `now`)",
+			"2. If the old hooks reference `data` (cross-field access), convert to a type-level hook",
+			"   using `input`/`oldRecord`",
+			"3. Remove unused `Hooks<F>` / `HookFn<>` type imports"
+		].join("\n")
+	},
+	{
+		id: "v2/erd-site-to-plugin",
+		name: "`db.<namespace>.erdSite` → `tailordbErdPlugin({ sites })`",
+		description: "Move the TailorDB `erdSite` setting from `db.<namespace>` in tailor.config.ts into `tailordbErdPlugin({ sites })` from `@tailor-platform/sdk-plugin-tailordb-erd`, registered via definePlugins(). The core config schema no longer accepts `erdSite`; the `tailor tailordb erd` commands read the target static website from the plugin configuration and validate each site name against `staticWebsites`. Install `@tailor-platform/sdk-plugin-tailordb-erd` as a dev dependency: the migrated config imports it, so config loading fails with a module-not-found error until it is installed.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_9,
+		scriptPath: "v2/erd-site-to-plugin/scripts/transform.js",
+		legacyPatterns: ["erdSite:"],
+		sourceStringLegacyPatterns: ["erdSite"],
+		suspiciousPatterns: [
+			"erdSite:",
+			/\berdSite\s*[,}]/,
+			"tailordbErdPlugin"
+		],
+		sourceStringSuspiciousPatterns: ["erdSite"],
+		examples: [{
+			before: [
+				"export default defineConfig({",
+				"  db: {",
+				"    tailordb: {",
+				"      files: [\"./tailordb/*.ts\"],",
+				"      erdSite: \"my-erd-site\",",
+				"    },",
+				"  },",
+				"});"
+			].join("\n"),
+			after: [
+				"import { tailordbErdPlugin } from \"@tailor-platform/sdk-plugin-tailordb-erd\";",
+				"",
+				"export default defineConfig({",
+				"  db: {",
+				"    tailordb: {",
+				"      files: [\"./tailordb/*.ts\"],",
+				"    },",
+				"  },",
+				"});",
+				"",
+				"export const plugins = definePlugins(",
+				"  tailordbErdPlugin({ sites: { tailordb: \"my-erd-site\" } }),",
+				");"
+			].join("\n")
+		}],
+		prompt: [
+			"In Tailor SDK v2 the TailorDB `erdSite` setting is removed from the core config",
+			"schema; the ERD deploy target is configured on the ERD CLI plugin instead. The",
+			"codemod rewrites literal `db.<namespace>.erdSite` entries inside top-level",
+			"defineConfig() calls into a `tailordbErdPlugin({ sites: { <namespace>: <value> } })`",
+			"argument of definePlugins(), importing it from @tailor-platform/sdk-plugin-tailordb-erd.",
+			"",
+			"First, for every config that now registers tailordbErdPlugin, make sure",
+			"@tailor-platform/sdk-plugin-tailordb-erd is installed as a dev dependency — the",
+			"migrated config imports it, so config loading fails with ERR_MODULE_NOT_FOUND",
+			"until it is installed.",
+			"",
+			"For any remaining `erdSite` config keys the codemod did not rewrite — a db config",
+			"built dynamically or passed via a variable, quoted or computed keys, spread",
+			"properties, a defineConfig() call inside a factory function, or a file that",
+			"already registers tailordbErdPlugin — move the namespace → static-website-name",
+			"mapping into tailordbErdPlugin({ sites }) and delete the `erdSite` key. For",
+			"factory-built configs, keep any referenced parameters or locals in scope when",
+			"moving the value to the module-level definePlugins() export. Each site name",
+			"must match a static website defined in staticWebsites. Leave unrelated",
+			"identifiers that merely contain the name (e.g. a defineStaticWebSite variable",
+			"named erdSite) unchanged."
+		].join("\n")
+	},
+	{
+		id: "v2/generate-watch-flag",
+		name: "generate --watch flag removed",
+		description: "Review and remove `tailor generate --watch` / `-W` invocations and the `watch` option on `GenerateOptions`. The flag, its dependency watcher, and the self-restart-on-change logic are removed; `generate` now always performs a single generation pass.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_6,
+		filePatterns: [
+			"**/package.json",
+			"**/*.{sh,bash,zsh,yml,yaml}",
+			"**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
+			"**/*.md"
+		],
+		suspiciousPatterns: [/\bgenerate\b[^\n]*(?:--watch\b|\s-W\b)/, [/\bgenerate\s*\(/, /\bwatch\s*:/]],
+		examples: [{
+			lang: "sh",
+			caption: "The --watch/-W flag no longer exists; re-run generate after each change:",
+			before: "tailor generate --watch",
+			after: "tailor generate"
+		}],
+		prompt: [
+			"Tailor SDK v2 removes the `generate --watch` (`-W`) flag along with the",
+			"dependency watcher and self-restart logic that powered it. `tailor generate`",
+			"now always runs a single generation pass and exits.",
+			"",
+			"For each flagged `tailor generate ... --watch` / `-W` invocation (package.json",
+			"scripts, shell scripts, CI configs, or docs), drop the flag and re-run",
+			"`tailor generate` after each change instead. If automatic regeneration on file",
+			"change is still needed, wrap the command with a general-purpose file watcher",
+			"(e.g. `chokidar-cli`, `nodemon`) at the project level.",
+			"",
+			"For programmatic use of `generate()` from `@tailor-platform/sdk/cli`, remove the",
+			"`watch` field from the `GenerateOptions` argument — the function now performs a",
+			"single generation pass and resolves once it completes."
+		].join("\n")
+	},
+	{
+		id: "v2/seed-exec-to-cli-plugin",
+		name: "Generated seed exec.mjs → tailor seed CLI plugin",
+		description: "`seedPlugin` no longer generates the `exec.mjs` seed runner. Seeding and validation move to the `tailor seed` commands provided by the `@tailor-platform/sdk-plugin-seed` CLI plugin: install it as a devDependency, replace `node <distPath>/exec.mjs` invocations with `tailor seed apply` and `node <distPath>/exec.mjs validate` with `tailor seed validate`, and delete the stale generated `<distPath>/exec.mjs` file. Seed data and schema generation (`data/*.jsonl`, `data/*.schema.ts`) is unchanged, and the `tailor seed apply` options mirror the old script (`--machine-user`, `--namespace`, `--skip-idp`, `--truncate`, `--yes`, type-name arguments).",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_9,
+		filePatterns: ["**/package.json", "**/*.{sh,yml,yaml,md,mjs,ts}"],
+		suspiciousPatterns: ["exec.mjs"],
+		sourceStringSuspiciousPatterns: ["exec.mjs"],
+		examples: [{
+			before: "\"seed\": \"node ./seed/exec.mjs\",\n\"seed:validate\": \"node ./seed/exec.mjs validate\"",
+			after: "\"seed\": \"tailor seed apply\",\n\"seed:validate\": \"tailor seed validate\"",
+			lang: "jsonc"
+		}],
+		prompt: [
+			"seedPlugin no longer generates the exec.mjs seed runner in v2. The tailor seed",
+			"CLI plugin (@tailor-platform/sdk-plugin-seed) replaces it:",
+			"",
+			"- Install @tailor-platform/sdk-plugin-seed as a devDependency next to",
+			"  @tailor-platform/sdk.",
+			"- Replace `node <distPath>/exec.mjs [options] [types...]` invocations with",
+			"  `tailor seed apply [options] [types...]` (same options: --machine-user/-m,",
+			"  --namespace/-n, --skip-idp, --truncate, --yes, and type-name arguments).",
+			"- Replace `node <distPath>/exec.mjs validate [path]` with",
+			"  `tailor seed validate [path]`.",
+			"- Delete the stale generated `<distPath>/exec.mjs` file; keep the data/",
+			"  directory (JSONL data and generated schemas) as-is."
+		].join("\n")
+	},
+	{
+		id: "v2/node-minimum-22-15-0",
+		name: "Node.js minimum version raised to 22.15.0",
+		description: "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+.",
+		since: "1.0.0",
+		until: "2.0.0",
+		notice: true
+	},
+	{
+		id: "v2/remove-legacy-bundle-cleanup",
+		name: "Legacy bundle artifact cleanup removed from deploy",
+		description: "`tailor deploy` no longer deletes on-disk bundle artifacts (`.entry.js` files, workflow-job bundles, and the `hooks-validate-scripts/` directory) left in the SDK output directory (`.tailor` by default) by SDK versions that predate the current in-memory bundling approach. Current bundlers no longer write these files. No source change is required; if such stale files remain from a very old SDK version, delete only those specific files/directories manually — do not delete the output directory itself, since it also holds deploy state (e.g. `secrets-state/`, `*.context.json`) that existing secrets and Auth Connections depend on.",
+		since: "1.0.0",
+		until: "2.0.0",
+		notice: true
 	}
 ];
 /**
@@ -125,9 +1231,33 @@ const allCodemods = [
 function resolveCodemodScript(scriptPath) {
 	return path.resolve(CODEMODS_ROOT, scriptPath);
 }
+function reachesCodemodBoundary(toVersion, codemod) {
+	if (gte(toVersion, codemod.until)) return true;
+	if (codemod.prereleaseUntil === void 0 || codemod.prereleaseUntil === "pending" || !gte(toVersion, codemod.prereleaseUntil)) return false;
+	const target = parse(toVersion);
+	const boundary = parse(codemod.until);
+	return target.prerelease.length > 0 && target.major === boundary.major && target.minor === boundary.minor && target.patch === boundary.patch;
+}
+function effectiveCodemodBoundary(codemod) {
+	if (codemod.prereleaseUntil === "pending") return codemod.until;
+	return codemod.prereleaseUntil ?? codemod.until;
+}
+function assertCodemodBoundaries(codemods) {
+	for (const codemod of codemods) {
+		const boundary = parse(codemod.until);
+		if (boundary === null) throw new Error(`Codemod ${codemod.id} until must be a valid semver version: ${codemod.until}`);
+		if (boundary.prerelease.length > 0) throw new Error(`Codemod ${codemod.id} until must be a stable version: ${codemod.until}`);
+		if (codemod.prereleaseUntil === void 0 || codemod.prereleaseUntil === "pending") continue;
+		const prereleaseBoundary = parse(codemod.prereleaseUntil);
+		if (prereleaseBoundary === null) throw new Error(`Codemod ${codemod.id} prereleaseUntil must be a valid semver version: ${codemod.prereleaseUntil}`);
+		if (prereleaseBoundary.prerelease.length === 0) throw new Error(`Codemod ${codemod.id} prereleaseUntil must be a prerelease version: ${codemod.prereleaseUntil}`);
+		if (prereleaseBoundary.major !== boundary.major || prereleaseBoundary.minor !== boundary.minor || prereleaseBoundary.patch !== boundary.patch) throw new Error(`Codemod ${codemod.id} prereleaseUntil must target the same version as until: ${codemod.prereleaseUntil}`);
+	}
+}
 /**
 * Get codemod packages applicable for a version range.
-* A codemod applies when: since <= fromVersion < until <= toVersion
+* A codemod applies when: since <= fromVersion < boundary <= toVersion.
+* A target prerelease reaches `until` only when the codemod declares `prereleaseUntil`.
 * @param fromVersion - Current SDK version (semver)
 * @param toVersion - Target SDK version (semver)
 * @returns Array of applicable codemod packages in registration order
@@ -135,7 +1265,8 @@ function resolveCodemodScript(scriptPath) {
 function getApplicableCodemods(fromVersion, toVersion) {
 	if (!valid(fromVersion)) throw new Error(`Invalid fromVersion: ${fromVersion}`);
 	if (!valid(toVersion)) throw new Error(`Invalid toVersion: ${toVersion}`);
-	return allCodemods.filter((codemod) => gte(fromVersion, codemod.since) && lt(fromVersion, codemod.until) && gte(toVersion, codemod.until));
+	assertCodemodBoundaries(allCodemods);
+	return allCodemods.filter((codemod) => gte(fromVersion, codemod.since) && lt(fromVersion, effectiveCodemodBoundary(codemod)) && reachesCodemodBoundary(toVersion, codemod));
 }
 //#endregion
 //#region src/runner.ts
@@ -147,6 +1278,68 @@ const EXCLUDE_DIRS = /* @__PURE__ */ new Set([
 	"dist",
 	".git"
 ]);
+const ALLOWED_DOT_DIRS = /* @__PURE__ */ new Set([".github", ".circleci"]);
+const SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+]);
+const SOURCE_STRING_FRAGMENT_SEPARATOR = "\0";
+const MASKED_SOURCE_NODE_KINDS = /* @__PURE__ */ new Set([
+	"comment",
+	"string",
+	"regex",
+	"string_fragment",
+	"jsx_text"
+]);
+const SOURCE_VALUE_FLAGS = /* @__PURE__ */ new Set([
+	"--env-file-if-exists",
+	"--env-file",
+	"--profile",
+	"--config",
+	"--workspace-id",
+	"--arg",
+	"--query",
+	"--file",
+	"--name",
+	"--namespace",
+	"--dir",
+	"-e",
+	"-p",
+	"-c",
+	"-w",
+	"-a",
+	"-q",
+	"-f",
+	"-n"
+]);
+const SOURCE_CLI_BINARY_RE = /^(?:(?:.*[\\/])?tailor(?:\.(?:cmd|ps1|exe))?|(?:.*[\\/])?tailor-sdk(?:@[^\s'"`;|&)]+)?(?:\.(?:cmd|ps1|exe))?|@tailor-platform\/sdk(?:@[^\s'"`;|&)]+)?)$/;
+function shouldSkipDirectory(name) {
+	return EXCLUDE_DIRS.has(name) || name.startsWith(".") && !ALLOWED_DOT_DIRS.has(name);
+}
+async function* walkFiles(root, relativeDir = "") {
+	const absoluteDir = path.join(root, relativeDir);
+	let entries;
+	try {
+		entries = await fs.promises.readdir(absoluteDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const relative = relativeDir ? path.join(relativeDir, entry.name) : entry.name;
+		if (entry.isDirectory()) {
+			if (shouldSkipDirectory(entry.name)) continue;
+			yield* walkFiles(root, relative);
+			continue;
+		}
+		if (entry.isFile()) yield relative;
+	}
+}
 /**
 * Print a colorized unified diff for a single file to stderr.
 * @param filePath - Absolute path to the file
@@ -169,12 +1362,301 @@ function printDiff(filePath, before, after) {
 * Load a transform module from a TypeScript file path.
 * Expects the module to have a default export that is a TransformFn.
 * @param scriptPath - Absolute path to the transform script
-* @returns The transform function
+* @returns The transform function and optional review detector
 */
-async function loadTransform(scriptPath) {
+async function loadTransformModule(scriptPath) {
 	const mod = await import(url.pathToFileURL(scriptPath).href);
 	if (typeof mod.default !== "function") throw new Error(`Transform at ${scriptPath} does not have a default export function`);
-	return mod.default;
+	return {
+		transform: mod.default,
+		reviewFindings: typeof mod.reviewFindings === "function" ? mod.reviewFindings : void 0
+	};
+}
+function contentForResidualMatching(relative, content) {
+	const ext = path.extname(relative).toLowerCase();
+	return SOURCE_EXTENSIONS.has(ext) ? maskSourceNonCode(relative, content) : content;
+}
+function sourceStringFragmentGapForResidualMatching(gap) {
+	if (/^\\["']$/.test(gap)) return gap.slice(1);
+	return /^(?:\\(?:[nrtvf]|\r\n|\r|\n)|\s)+$/.test(gap) ? " " : SOURCE_STRING_FRAGMENT_SEPARATOR;
+}
+function sourceStringNodeContentForResidualMatching(node, content) {
+	const parts = [];
+	let previousFragmentEnd = null;
+	for (const child of node.children()) {
+		if (child.kind() !== "string_fragment") continue;
+		const range = child.range();
+		if (previousFragmentEnd != null && range.start.index > previousFragmentEnd) parts.push(sourceStringFragmentGapForResidualMatching(content.slice(previousFragmentEnd, range.start.index)));
+		parts.push(child.text());
+		previousFragmentEnd = range.end.index;
+	}
+	return parts.length === 0 ? null : parts.join("");
+}
+function sourceStringContentForResidualMatching(relative, content) {
+	const ext = path.extname(relative).toLowerCase();
+	if (!SOURCE_EXTENSIONS.has(ext)) return null;
+	let root;
+	try {
+		root = parse$1(sourceLang(relative), content).root();
+	} catch {
+		return null;
+	}
+	const sourceStrings = [];
+	const visit = (node) => {
+		if (node.kind() === "arguments") {
+			const value = sourceArgumentsCommandContent(node, content);
+			if (value != null) sourceStrings.push(value);
+		}
+		if (node.kind() === "array") {
+			const value = sourceArrayCommandContent(node, content);
+			if (value != null) sourceStrings.push(value);
+		}
+		const kind = node.kind();
+		if (kind === "string" || kind === "template_string") {
+			if (isSourceTailorSdkValueArgument(node, content)) return;
+			const sourceString = sourceStringNodeContentForResidualMatching(node, content);
+			if (sourceString != null) sourceStrings.push(sourceString);
+		}
+		for (const child of node.children()) {
+			if (child.kind() === "string_fragment") continue;
+			visit(child);
+		}
+	};
+	visit(root);
+	return sourceStrings.join(SOURCE_STRING_FRAGMENT_SEPARATOR);
+}
+function isConstVariableDeclarator(node) {
+	return node.parent()?.children().some((child) => child.kind() === "const") ?? false;
+}
+function sourceTextContentForResidualMatching(relative, content) {
+	const ext = path.extname(relative).toLowerCase();
+	if (!SOURCE_EXTENSIONS.has(ext)) return null;
+	let root;
+	try {
+		root = parse$1(sourceLang(relative), content).root();
+	} catch {
+		return null;
+	}
+	const fragments = [];
+	const visit = (node) => {
+		if (node.kind() === "comment" || node.kind() === "jsx_text") {
+			fragments.push(node.text());
+			return;
+		}
+		for (const child of node.children()) visit(child);
+	};
+	visit(root);
+	return fragments.join(SOURCE_STRING_FRAGMENT_SEPARATOR);
+}
+function sourceArgumentsCommandContent(node, source) {
+	const args = sourceArrayElements(node);
+	const executable = args[0] == null ? null : sourceStringLikeNodeContent(args[0], source);
+	const argv = args[1];
+	if (executable == null || argv?.kind() !== "array") return null;
+	const values = sourceArrayCommandValues(argv, source);
+	return values.length === 0 ? null : [executable, ...values].join(" ");
+}
+function sourceArrayCommandContent(node, source) {
+	const values = sourceArrayCommandValues(node, source);
+	return values.length < 2 ? null : values.join(" ");
+}
+function sourceArrayCommandValues(node, source) {
+	const values = [];
+	for (const element of sourceArrayElements(node)) {
+		if (isSourceValueArgument(element, source)) continue;
+		const value = sourceStringLikeNodeContent(element, source);
+		if (value != null) values.push(value);
+	}
+	return values;
+}
+function isSourceTailorSdkValueArgument(fragment, source) {
+	const text = fragment.kind() === "string_fragment" ? fragment.text() : sourceStringLikeNodeContent(fragment, source);
+	return text != null && text.includes("tailor-sdk") && isSourceValueArgument(fragment, source);
+}
+function isSyntaxOnlyNode(node) {
+	const kind = node.kind();
+	return kind === "[" || kind === "]" || kind === "(" || kind === ")" || kind === "," || kind === "comment";
+}
+function sourceArrayElements(node) {
+	return node.children().filter((child) => !isSyntaxOnlyNode(child));
+}
+function nodeRangeKey(node) {
+	const range = node.range();
+	return `${range.start.index}:${range.end.index}`;
+}
+function sourceStringLikeNodeContent(node, source) {
+	const directValue = sourceStringNodeContent(node, source);
+	if (directValue != null) return directValue;
+	return node.kind() === "identifier" ? sourceScopedStringVariableContent(node, source) : null;
+}
+function sourceScopedStringVariableContent(identifier, source) {
+	const name = identifier.text();
+	const before = identifier.range().start.index;
+	let current = identifier.parent();
+	while (current != null) {
+		if (isSourceScopeNode(current)) {
+			const value = findSourceStringVariableInScope(current, name, before, source);
+			if (value != null) return value;
+		}
+		current = current.parent();
+	}
+	return null;
+}
+function findSourceStringVariableInScope(scope, name, before, source) {
+	let value = null;
+	const visit = (node) => {
+		if (node !== scope && isSourceScopeNode(node)) return;
+		if (node.kind() === "variable_declarator" && node.range().end.index < before) {
+			const declarationValue = sourceStringVariableDeclarationValue(node, name, source);
+			if (declarationValue != null) value = declarationValue;
+			return;
+		}
+		for (const child of node.children()) visit(child);
+	};
+	visit(scope);
+	return value;
+}
+function sourceStringVariableDeclarationValue(node, name, source) {
+	if (!isConstVariableDeclarator(node)) return null;
+	const children = node.children();
+	if (children.find((child) => child.kind() === "identifier")?.text() !== name) return null;
+	const initializer = children.findLast((child) => sourceConstInitializerContent(child, source) != null);
+	return initializer == null ? null : sourceConstInitializerContent(initializer, source);
+}
+function sourceConstInitializerContent(node, source) {
+	const directValue = sourceStringNodeContent(node, source);
+	if (directValue != null) return directValue;
+	if (node.kind() !== "as_expression" && node.kind() !== "satisfies_expression" && node.kind() !== "parenthesized_expression") return null;
+	for (const child of node.children()) {
+		const childValue = sourceConstInitializerContent(child, source);
+		if (childValue != null) return childValue;
+	}
+	return null;
+}
+function isSourceScopeNode(node) {
+	const kind = node.kind();
+	return kind === "program" || kind === "statement_block" || kind === "function_declaration" || kind === "arrow_function" || kind === "method_definition";
+}
+function sourceStringNodeContent(node, source) {
+	const kind = node.kind();
+	if (kind !== "string" && kind !== "template_string") return null;
+	if (kind === "template_string" && node.children().some((child) => child.kind() === "template_substitution")) return null;
+	const range = node.range();
+	return source.slice(range.start.index + 1, range.end.index - 1);
+}
+function isSourceValueArgument(fragment, source) {
+	const stringNode = fragment.kind() === "string_fragment" ? fragment.parent() : fragment;
+	if (stringNode == null) return false;
+	const parent = stringNode.parent();
+	if (parent?.kind() !== "array") return false;
+	const elements = sourceArrayElements(parent);
+	const index = elements.findIndex((element) => nodeRangeKey(element) === nodeRangeKey(stringNode));
+	if (index <= 0) return false;
+	if (!isTailorCliArgumentArray(parent, index, source)) return false;
+	const previous = sourceStringLikeNodeContent(elements[index - 1], source);
+	return previous != null && SOURCE_VALUE_FLAGS.has(previous.split("=", 1)[0]) && !previous.includes("=");
+}
+function isTailorCliArgumentArray(arrayNode, index, source) {
+	const argumentsNode = arrayNode.parent();
+	if (argumentsNode?.kind() === "arguments") {
+		const callArgs = sourceArrayElements(argumentsNode);
+		const executable = callArgs[0] == null ? null : sourceStringLikeNodeContent(callArgs[0], source);
+		if (executable != null && SOURCE_CLI_BINARY_RE.test(executable)) return true;
+	}
+	return sourceArrayElements(arrayNode).slice(0, index).some((element) => {
+		const value = sourceStringLikeNodeContent(element, source);
+		return value != null && SOURCE_CLI_BINARY_RE.test(value);
+	});
+}
+function sourceLang(relative) {
+	const ext = path.extname(relative).toLowerCase();
+	return ext === ".tsx" || ext === ".jsx" || ext === ".js" ? Lang.Tsx : Lang.TypeScript;
+}
+function isProcessEnvSubscriptKey(node) {
+	const stringNode = node.kind() === "string_fragment" ? node.parent() : node;
+	if (stringNode == null) return false;
+	const stringNodeKind = stringNode.kind();
+	if (stringNodeKind !== "string" && stringNodeKind !== "template_string") return false;
+	const parent = stringNode.parent();
+	return parent?.kind() === "subscript_expression" && /^process\.env\s*\[/.test(parent.text());
+}
+function collectMaskedRanges(root) {
+	const ranges = [];
+	const visit = (node) => {
+		if (MASKED_SOURCE_NODE_KINDS.has(node.kind())) {
+			if (isProcessEnvSubscriptKey(node)) return;
+			const range = node.range();
+			ranges.push([range.start.index, range.end.index]);
+			return;
+		}
+		for (const child of node.children()) visit(child);
+	};
+	visit(root);
+	return ranges;
+}
+function maskSourceNonCode(relative, content) {
+	let ranges;
+	try {
+		ranges = collectMaskedRanges(parse$1(sourceLang(relative), content).root());
+	} catch {
+		return content;
+	}
+	ranges = ranges.toSorted(([a], [b]) => a - b);
+	const chars = content.split("");
+	for (const [start, end] of ranges) for (let i = start; i < end && i < chars.length; i++) if (chars[i] !== "\n" && chars[i] !== "\r") chars[i] = " ";
+	return chars.join("");
+}
+function isIdentifierChar(char) {
+	return char != null && /^[A-Za-z0-9_$]$/.test(char);
+}
+function matchesPattern(content, pattern) {
+	if (typeof pattern === "string") {
+		const checkLeft = isIdentifierChar(pattern[0]);
+		const checkRight = isIdentifierChar(pattern.at(-1));
+		let index = content.indexOf(pattern);
+		while (index !== -1) {
+			const before = index > 0 ? content[index - 1] : void 0;
+			const after = content[index + pattern.length];
+			if ((!checkLeft || !isIdentifierChar(before)) && (!checkRight || !isIdentifierChar(after))) return true;
+			index = content.indexOf(pattern, index + 1);
+		}
+		return false;
+	}
+	pattern.lastIndex = 0;
+	return pattern.test(content);
+}
+function patternLabel(pattern) {
+	return typeof pattern === "string" ? pattern : pattern.toString();
+}
+/** Resolve a residual pattern against content, returning its label when matched. */
+function matchResidualPattern(content, pattern) {
+	if (!Array.isArray(pattern)) return matchesPattern(content, pattern) ? patternLabel(pattern) : null;
+	return pattern.every((p) => matchesPattern(content, p)) ? pattern.map((p) => patternLabel(p)).join(" + ") : null;
+}
+function matchResidualPatternFragment(content, pattern) {
+	for (const fragment of content.split(SOURCE_STRING_FRAGMENT_SEPARATOR)) {
+		const label = matchResidualPattern(fragment, pattern);
+		if (label != null) return label;
+	}
+	return null;
+}
+function legacyPatternWarnings(relative, content, sourceStringContent, sourceTextContent, transforms) {
+	return transforms.flatMap((lt) => {
+		const found = new Set(lt.legacyPatterns.map((p) => matchResidualPattern(content, p)).filter((label) => label !== null));
+		if (sourceStringContent != null) for (const pattern of lt.sourceStringLegacyPatterns) {
+			const label = matchResidualPatternFragment(sourceStringContent, pattern);
+			if (label != null) found.add(label);
+		}
+		if (sourceTextContent != null) for (const pattern of lt.sourceTextLegacyPatterns) {
+			const label = matchResidualPatternFragment(sourceTextContent, pattern);
+			if (label != null) found.add(label);
+		}
+		if (found.size === 0) return [];
+		return [`${relative}: contains ${Array.from(found).join(", ")} but was not migrated automatically (rule: ${lt.id}). Manual migration may be needed.`];
+	});
+}
+function compareReviewFindings(a, b) {
+	return a.file.localeCompare(b.file) || a.line - b.line || a.message.localeCompare(b.message) || a.excerpt.localeCompare(b.excerpt);
 }
 /**
 * Run multiple codemods on a project directory using in-memory chaining.
@@ -191,26 +1673,33 @@ async function runCodemods(codemods, targetPath, dryRun) {
 	const loaded = [];
 	for (const { codemod, scriptPath } of codemods) {
 		const patterns = codemod.filePatterns ?? DEFAULT_FILE_PATTERNS;
+		const loadedModule = scriptPath ? await loadTransformModule(scriptPath) : void 0;
 		loaded.push({
 			id: codemod.id,
-			transform: await loadTransform(scriptPath),
-			matches: picomatch(patterns),
-			legacyPatterns: codemod.legacyPatterns ?? []
+			transform: loadedModule?.transform,
+			reviewFindings: loadedModule?.reviewFindings,
+			matches: picomatch(patterns, { dot: true }),
+			legacyPatterns: codemod.legacyPatterns ?? [],
+			sourceStringLegacyPatterns: codemod.sourceStringLegacyPatterns ?? [],
+			sourceTextLegacyPatterns: codemod.sourceTextLegacyPatterns ?? [],
+			suspiciousPatterns: codemod.suspiciousPatterns ?? [],
+			sourceStringSuspiciousPatterns: codemod.sourceStringSuspiciousPatterns ?? [],
+			prompt: codemod.prompt,
+			reviewSupersededBy: codemod.reviewSupersededBy ?? []
 		});
 	}
-	const allPatterns = /* @__PURE__ */ new Set();
-	for (const { codemod } of codemods) for (const p of codemod.filePatterns ?? DEFAULT_FILE_PATTERNS) allPatterns.add(p);
 	const filesModified = [];
 	const warnings = [];
 	const appliedCodemodIds = /* @__PURE__ */ new Set();
 	const seen = /* @__PURE__ */ new Set();
-	for (const pattern of allPatterns) for await (const relative of glob(pattern, {
-		cwd: targetPath,
-		exclude: (name) => EXCLUDE_DIRS.has(name)
-	})) {
+	const suspiciousByCodemod = /* @__PURE__ */ new Map();
+	const findingsByCodemod = /* @__PURE__ */ new Map();
+	for await (const relative of walkFiles(targetPath)) {
 		const absolute = path.resolve(targetPath, relative);
 		if (seen.has(absolute)) continue;
 		seen.add(absolute);
+		const matchedTransforms = loaded.filter((lt) => lt.matches(relative));
+		if (matchedTransforms.length === 0) continue;
 		let original;
 		try {
 			original = await fs.promises.readFile(absolute, "utf-8");
@@ -218,10 +1707,8 @@ async function runCodemods(codemods, targetPath, dryRun) {
 			continue;
 		}
 		let current = original;
-		const matchedTransforms = [];
-		for (const lt of loaded) {
-			if (!lt.matches(relative)) continue;
-			matchedTransforms.push(lt);
+		for (const lt of matchedTransforms) {
+			if (!lt.transform) continue;
 			const result = await lt.transform(current, absolute);
 			if (result != null) {
 				current = result;
@@ -232,25 +1719,191 @@ async function runCodemods(codemods, targetPath, dryRun) {
 			filesModified.push(absolute);
 			if (dryRun) printDiff(absolute, original, current);
 			else await fs.promises.writeFile(absolute, current, "utf-8");
-		} else for (const lt of matchedTransforms) {
-			const found = lt.legacyPatterns.filter((p) => original.includes(p));
-			if (found.length > 0) warnings.push(`${relative}: contains ${found.join(", ")} but was not migrated automatically (rule: ${lt.id}). Manual migration may be needed.`);
+		}
+		const residualContent = contentForResidualMatching(relative, current);
+		const sourceStringContent = sourceStringContentForResidualMatching(relative, current);
+		const sourceTextContent = sourceTextContentForResidualMatching(relative, current);
+		warnings.push(...legacyPatternWarnings(relative, residualContent, sourceStringContent, sourceTextContent, matchedTransforms));
+		for (const lt of matchedTransforms) {
+			if (!lt.prompt) continue;
+			const filesForReview = () => {
+				let files = suspiciousByCodemod.get(lt.id);
+				if (!files) {
+					files = /* @__PURE__ */ new Set();
+					suspiciousByCodemod.set(lt.id, files);
+				}
+				return files;
+			};
+			if (lt.reviewFindings) {
+				const findings = await lt.reviewFindings(current, absolute, relative);
+				if (findings.length > 0) {
+					const files = filesForReview();
+					for (const finding of findings) files.add(finding.file);
+					let existing = findingsByCodemod.get(lt.id);
+					if (!existing) {
+						existing = [];
+						findingsByCodemod.set(lt.id, existing);
+					}
+					existing.push(...findings);
+				}
+			}
+			if (lt.suspiciousPatterns.some((p) => matchResidualPattern(residualContent, p) !== null) || sourceStringContent != null && lt.sourceStringSuspiciousPatterns.some((p) => matchResidualPattern(sourceStringContent, p) !== null)) filesForReview().add(relative);
 		}
 	}
+	const llmReviews = [];
+	const loadedIds = new Set(loaded.map((lt) => lt.id));
+	for (const lt of loaded) {
+		if (!lt.prompt) continue;
+		if (lt.reviewSupersededBy.some((id) => loadedIds.has(id))) continue;
+		if (lt.suspiciousPatterns.length > 0 || lt.sourceStringSuspiciousPatterns.length > 0 || lt.reviewFindings) {
+			const files = suspiciousByCodemod.get(lt.id);
+			if (files) {
+				const findings = findingsByCodemod.get(lt.id)?.toSorted(compareReviewFindings);
+				llmReviews.push({
+					codemodId: lt.id,
+					prompt: lt.prompt,
+					files: Array.from(files).toSorted(),
+					...findings && findings.length > 0 ? { findings } : {}
+				});
+			}
+		} else if (lt.legacyPatterns.length === 0) llmReviews.push({
+			codemodId: lt.id,
+			prompt: lt.prompt,
+			files: []
+		});
+	}
 	return {
 		changed: filesModified.length > 0,
 		filesModified,
 		warnings,
-		appliedCodemodIds
+		appliedCodemodIds,
+		llmReviews
 	};
 }
 //#endregion
+//#region src/runner-metadata.ts
+const SOURCE_PACKAGE_PATH = "packages/sdk-codemod";
+const LOCAL_BUILD_COMMAND = "pnpm --dir packages/sdk-codemod build";
+function createRunnerMetadata({ packageName, packageVersion, packageRoot, readGit = readGitOutput, realpath = safeRealpath }) {
+	const metadata = {
+		packageName,
+		packageVersion
+	};
+	const gitRoot = readGit(packageRoot, ["rev-parse", "--show-toplevel"]);
+	if (!gitRoot) return metadata;
+	if (path.normalize(path.relative(realpath(gitRoot), realpath(packageRoot))).replaceAll("\\", "/") !== SOURCE_PACKAGE_PATH) return metadata;
+	const gitCommit = readGit(packageRoot, [
+		"rev-parse",
+		"--verify",
+		"HEAD"
+	]);
+	if (!gitCommit) return metadata;
+	return {
+		...metadata,
+		gitCommit,
+		localBuildCommand: LOCAL_BUILD_COMMAND
+	};
+}
+function readGitOutput(cwd, args) {
+	try {
+		return execFileSync("git", [
+			"-C",
+			cwd,
+			...args
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim() || void 0;
+	} catch {
+		return;
+	}
+}
+function safeRealpath(value) {
+	try {
+		return realpathSync(value);
+	} catch {
+		return path.resolve(value);
+	}
+}
+//#endregion
 //#region src/index.ts
-const packageJson = await readPackageJSON(path.dirname(fileURLToPath(import.meta.url)) + "/..");
+const packageRoot = path.dirname(fileURLToPath(import.meta.url)) + "/..";
+const packageJson = await readPackageJSON(packageRoot);
+const packageName = packageJson.name ?? "sdk-codemod";
+const packageVersion = packageJson.version ?? "0.0.0";
+const listCommand = defineCommand({
+	name: "list",
+	description: "List the available codemod rules (id, name, kind, version range).",
+	args: z.strictObject({}),
+	run: () => {
+		const rules = allCodemods.map((codemod) => ({
+			id: codemod.id,
+			name: codemod.name,
+			kind: codemod.notice ? "Notice" : automationLevel(codemod),
+			since: codemod.since,
+			until: codemod.until
+		}));
+		for (const rule of rules) process.stderr.write(`  ${rule.id}  [${rule.kind}]  ${rule.name}\n`);
+		process.stdout.write(JSON.stringify(rules) + "\n");
+	}
+});
+/**
+* Print an LLM-assisted review task to stderr: the flagged files plus the
+* codemod's migration prompt, ready to hand to an LLM for the cases the
+* deterministic transform could not complete on its own.
+* @param review - The review task (codemod id, prompt, files)
+*/
+function printLlmReview(review) {
+	const scope = review.files.length > 0 ? "the codemod cannot safely migrate these automatically" : "review the project for this manual change";
+	process.stderr.write(`\n🤖 LLM-assisted review suggested (${review.codemodId}) — ${scope}:\n`);
+	const findingsByFile = /* @__PURE__ */ new Map();
+	for (const finding of review.findings ?? []) {
+		let findings = findingsByFile.get(finding.file);
+		if (!findings) {
+			findings = [];
+			findingsByFile.set(finding.file, findings);
+		}
+		findings.push(finding);
+	}
+	for (const file of review.files) {
+		process.stderr.write(`  - ${file}\n`);
+		for (const finding of findingsByFile.get(file) ?? []) {
+			process.stderr.write(`    - line ${finding.line}: ${finding.message}\n`);
+			process.stderr.write(`      ${finding.excerpt}\n`);
+		}
+	}
+	process.stderr.write(`\nPrompt for an LLM:\n${review.prompt.trim()}\n`);
+}
 runMain(defineCommand({
-	name: packageJson.name ?? "sdk-codemod",
+	name: packageName,
 	description: packageJson.description ?? "Codemod runner for Tailor Platform SDK upgrades",
-	args: z.object({
+	subCommands: { list: listCommand },
+	notes: `Applies the codemods matching the \`--from\`/\`--to\` version range to the
+\`--target\` directory, then writes a JSON summary to \`stdout\`:
+
+- \`filesModified\`: files a codemod changed
+- \`warnings\`: files that may still need manual migration
+- \`llmReviews\`: changes the codemods could not fully migrate on their own. Each
+  entry has the affected \`files\`, optional file-local \`findings\`, and a
+  \`prompt\` — hand the prompt and files to an LLM (or follow it yourself) to
+  finish those cases.
+- \`runner\`: exact codemod runner identity. Local source builds include the
+  repository commit and the build command used to produce \`dist/index.js\`.
+
+Progress, warnings, and the LLM-review prompts are also printed to \`stderr\` in
+human-readable form, so \`stdout\` stays pure JSON for piping.`,
+	examples: [{
+		cmd: "--from 1.64.0 --to 2.0.0",
+		desc: "Apply every codemod for the 1.64.0 -> 2.0.0 upgrade to the current project"
+	}, {
+		cmd: "--from 1.64.0 --to 2.0.0 --dry-run",
+		desc: "Preview the changes and any LLM-review prompts without writing files"
+	}],
+	args: z.strictObject({
 		from: arg(z.string(), { description: "Source SDK version (the version before upgrade)" }),
 		to: arg(z.string(), { description: "Target SDK version (the version after upgrade)" }),
 		target: arg(z.string().default("."), { description: "Project directory to transform" }),
@@ -258,17 +1911,24 @@ runMain(defineCommand({
 			alias: "d",
 			description: "Preview changes without modifying files"
 		})
-	}).strict(),
+	}),
 	run: async (args) => {
 		const targetPath = path.resolve(args.target);
 		const dryRun = args["dry-run"];
+		const runner = createRunnerMetadata({
+			packageName,
+			packageVersion,
+			packageRoot
+		});
 		const codemods = getApplicableCodemods(args.from, args.to);
 		const output = {
+			runner,
 			codemodsApplied: 0,
 			codemodsSkipped: 0,
 			filesModified: [],
 			warnings: [],
-			errors: []
+			errors: [],
+			llmReviews: []
 		};
 		if (codemods.length === 0) {
 			process.stdout.write(JSON.stringify(output) + "\n");
@@ -276,7 +1936,7 @@ runMain(defineCommand({
 		}
 		const codemodEntries = codemods.map((codemod) => ({
 			codemod,
-			scriptPath: resolveCodemodScript(codemod.scriptPath)
+			scriptPath: codemod.scriptPath ? resolveCodemodScript(codemod.scriptPath) : void 0
 		}));
 		for (const { codemod } of codemodEntries) process.stderr.write(`Running: ${codemod.name} - ${codemod.description}\n`);
 		try {
@@ -285,8 +1945,10 @@ runMain(defineCommand({
 			output.codemodsSkipped = codemods.length - result.appliedCodemodIds.size;
 			output.filesModified = result.filesModified;
 			output.warnings = result.warnings;
+			output.llmReviews = result.llmReviews;
 			if (result.changed) process.stderr.write(`  ${result.filesModified.length} file(s) modified\n`);
 			else process.stderr.write("  No changes needed\n");
+			for (const review of output.llmReviews) printLlmReview(review);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			output.errors.push({
@@ -298,6 +1960,6 @@ runMain(defineCommand({
 		process.stdout.write(JSON.stringify(output) + "\n");
 		if (output.errors.length > 0) process.exit(1);
 	}
-}), { version: packageJson.version });
+}), { version: packageVersion });
 //#endregion
 export {};