feat(docs): add API deployment migration guide

Add migration guide section to README documenting the transition
from CLI-based to API-based deployment introduced in #325.
Includes vercel-args to API inputs mapping table, step-by-step
migration instructions, and deprecated inputs reference.

Author: amondnet

README.md

@@ -360,6 +360,87 @@ The deployment lifecycle:
 
 > **Note:** GitHub Deployment errors are non-blocking. If the GitHub API call fails, the Vercel deployment will still proceed normally.
 
+## Migration to API-based Deployment (v42.2.0+)
+
+Starting with v42.2.0, this action uses the `@vercel/client` API by default instead of the Vercel CLI. This is **not a breaking change** — existing workflows using `vercel-args` will continue to work via CLI fallback.
+
+### What changed
+
+| Before (CLI via `vercel-args`)  | After (API inputs)          |
+|---------------------------------|-----------------------------|
+| `vercel-args: --prod`           | `target: production`        |
+| `vercel-args: --prebuilt`       | `prebuilt: true`            |
+| `vercel-args: --force`          | `force: true`               |
+| `vercel-args: --public`         | `public: true`              |
+| `vercel-args: --with-cache`     | `with-cache: true`          |
+| `vercel-args: --archive=tgz`    | `archive: tgz`              |
+| `vercel-args: --regions iad1`   | `regions: iad1`             |
+| `vercel-args: --env KEY=VAL`    | `env: KEY=VAL` (multiline)  |
+| `vercel-args: --build-env K=V`  | `build-env: K=V` (multiline)|
+| `scope: my-team`                | `vercel-org-id: team_xxx`   |
+
+### Migration steps
+
+1. **Remove `vercel-args`** and replace with equivalent API inputs:
+
+   ```yaml
+   # Before
+   - uses: amondnet/vercel-action@v25
+     with:
+       vercel-token: ${{ secrets.VERCEL_TOKEN }}
+       vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+       vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+       vercel-args: --prod --force
+
+   # After
+   - uses: amondnet/vercel-action@v25
+     with:
+       vercel-token: ${{ secrets.VERCEL_TOKEN }}
+       vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+       vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+       target: production
+       force: true
+   ```
+
+2. **Replace `scope`** with `vercel-org-id` (your team ID):
+
+   ```yaml
+   # Before
+   scope: my-team-slug
+
+   # After
+   vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}  # team_xxxxx
+   ```
+
+3. **Prebuilt deployments** — use the `prebuilt` input:
+
+   ```yaml
+   - uses: amondnet/vercel-action@v25
+     with:
+       vercel-token: ${{ secrets.VERCEL_TOKEN }}
+       vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+       vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+       prebuilt: true
+       target: production
+   ```
+
+### Keeping CLI mode
+
+If you prefer to stay on CLI-based deployment, simply keep using `vercel-args`. The action will automatically use the CLI client when `vercel-args` is provided:
+
+```yaml
+- uses: amondnet/vercel-action@v25
+  with:
+    vercel-args: --prod --force  # CLI fallback
+```
+
+### Deprecated inputs
+
+| Input          | Status       | Replacement                |
+|----------------|--------------|----------------------------|
+| `vercel-args`  | Deprecated   | Use API inputs (`target`, `prebuilt`, `force`, etc.) |
+| `scope`        | Deprecated   | Use `vercel-org-id`        |
+
 ## Migration from v2
 
 1. Change action name in `workflows` from `now-deployment` to `vercel-action`