docs: add documentation for deploymentId: "latest" in start()

.changeset/docs-deploymentid-latest.md

@@ -0,0 +1,5 @@
+---
+"@workflow/core": patch
+---
+
+Remove `@deprecated` tag from `deploymentId` in `StartOptions`

docs/content/docs/api-reference/workflow-api/start.mdx

@@ -76,3 +76,27 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
   deploymentId: "custom-deployment-id" // [!code highlight]
 }); // [!code highlight]
 ```
+
+### Using `deploymentId: "latest"`
+
+Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call.
+
+```typescript
+import { start } from "workflow/api";
+import { myWorkflow } from "./workflows/my-workflow";
+
+const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
+  deploymentId: "latest" // [!code highlight]
+}); // [!code highlight]
+```
+
+<Callout type="info">
+The `deploymentId` option is currently a Vercel-specific feature. The `"latest"` value resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+</Callout>
+
+<Callout type="warn">
+When using `deploymentId: "latest"`, the workflow run will execute on a potentially different deployment than the one calling `start()`. Be mindful of forward and backward compatibility:
+
+- **Workflow identity**: The workflow ID is derived from the function name and file path. If the latest deployment has renamed the workflow function or moved it to a different directory, the workflow ID will no longer match and the run will fail to start.
+- **Input and output compatibility**: The arguments passed to `start()` are serialized by the calling deployment but deserialized by the target deployment. Similarly, the workflow's return value is serialized by the target deployment but deserialized by the caller. If the workflow's expected arguments or return type have changed (e.g. added required fields, removed fields, or changed types), the run may fail or behave unexpectedly. Ensure that input and output schemas remain backward-compatible across deployments.
+</Callout>

docs/content/docs/foundations/common-patterns.mdx

@@ -252,6 +252,10 @@ export async function processOrder(orderId: string) {
 
 With background execution, the parent workflow continues immediately after starting the child. The child workflow runs independently with its own event log and can be monitored separately using the returned `runId`.
 
+<Callout type="info">
+If you want the child workflow to run on the latest deployment rather than the current one, you can pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. This is currently a Vercel-specific feature. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
+</Callout>
+
 **Choose direct await when:**
 - The parent needs the child's result before continuing
 - You want a single, unified event log

packages/core/src/runtime/start.ts

@@ -21,13 +21,12 @@ export interface StartOptions {
   /**
    * The deployment ID to use for the workflow run.
    *
+   * By default, this is automatically inferred from environment variables
+   * when deploying to Vercel.
+   *
    * Set to `'latest'` to automatically resolve the most recent deployment
    * for the current environment (same production target or git branch).
-   * Requires a World that implements `resolveLatestDeploymentId()`.
-   *
-   * @deprecated This property should not be set in user code under normal circumstances.
-   * It is automatically inferred from environment variables when deploying to Vercel.
-   * Only set this if you are doing something advanced and know what you are doing.
+   * This is currently a Vercel-specific feature.
    */
   deploymentId?: 'latest' | (string & {});