feat: make CLI deployment default, gate API behind experimental-api flag (#363)

* docs(track): add cli-default-experimental-api-20260430

Plan to make CLI deployment the default and gate API behind an
opt-in experimental-api input. Refs #362.

* chore(track): start cli-default-experimental-api-20260430 implementation

* feat(config): add experimental-api input with mutual-exclusion validation

- Add experimental-api boolean input to action.yml (default: false)
- Add experimentalApi field to ActionConfig type
- Parse the new input in getActionConfig(); throw on mutual exclusion
  with vercel-args
- Cover defaults, parsing, and mutual-exclusion error in config tests

Phase 1 (T001-T004) of cli-default-experimental-api-20260430. Refs #362.

* feat(vercel): default routing to CLI; gate API behind experimentalApi flag

createVercelClient() now routes to VercelCliClient by default and to
VercelApiClient only when config.experimentalApi is true, emitting a
core.warning that the API path is experimental and may break across
@vercel/client updates.

Routing tests rewritten as the four-case matrix from spec AC-1; the
mutual-exclusion case is enforced upstream in getActionConfig().

Phase 2 (T005-T007) of cli-default-experimental-api-20260430. Refs #362.

* docs: document CLI default with experimental-api opt-in

- action.yml: real description for vercel-args; reword scope deprecation
  message so it no longer ties scope to vercel-args presence
- README.md: replace 'Migration to API-based Deployment' section with a
  new 'Deployment Mode' section covering CLI default, experimental-api
  opt-in, the experimental warning, mutual-exclusion rule, CLI ↔ API
  input mapping, API-only inputs, and a migration note for users who
  relied on the previous v42 API default
- README.md: rename 'API Deployment Inputs (New)' to 'Experimental API
  Deployment Inputs' and gate them on experimental-api: true
- README.md: drop 'Deprecated' label on vercel-args / scope; add an
  experimental-api row to the inputs table

Phase 3 + Phase 4 (T008-T010) of cli-default-experimental-api-20260430.
Refs #362.

* test(integration): add factory routing tests + rebuild dist

- Add experimentalApi to integration createConfig helper (compile fix)
- Add factory routing tests: default config -> VercelCliClient (no warning);
  experimental-api: true -> VercelApiClient (with warning containing
  'experimental' and '@vercel/client')
- Rebuild dist/index.js with the new routing and config validation

Phase 5 (T011-T012) of cli-default-experimental-api-20260430. All 244
unit tests + 19 integration tests pass. Refs #362.

* docs(track): sync product.md with cli-default-experimental-api

* fix(action): remove deprecationMessage from scope input

Spec FR-6 requires removing the deprecationMessage from scope; the
description retains the vercel-org-id preference guidance, so the input
is still discoverable but no longer marked deprecated. CLI is now the
standard mode and scope is only relevant there.

Refs #362.

* refactor(types): encode deployment mode as discriminated union

Replace ActionConfig.vercelArgs (string) and ActionConfig.experimentalApi
(boolean) with a single discriminated union field:

  type DeploymentMode =
    | { kind: 'cli', vercelArgs: string }
    | { kind: 'experimental-api' }

  interface ActionConfig {
    deployment: DeploymentMode
    // ...
  }

Rationale (from review:review-type-analyzer, confidence 82): the previous
two-field shape made the (experimental-api: true, vercel-args: '--prod')
pair typecheck even though it is illegal at runtime. The discriminated
union makes that combination unrepresentable — the absence of vercelArgs
on the 'experimental-api' variant is enforced by the type system.

The runtime mutual-exclusion check still lives in config.ts, but it is
now a pure input-parsing concern: it transforms raw action.yml inputs
into one of the two valid type states, throwing if both inputs claim
to be set.

createVercelClient() switches on deployment.kind with an exhaustive
match. VercelCliClient narrows config.deployment.kind === 'cli' before
reading vercelArgs.

Test fixtures across config/vercel/integration tests updated to the new
shape; assertions on config.vercelArgs become assertions on
config.deployment shape.

All 243 unit + 19 integration tests pass; typecheck + lint clean; dist
rebuilt.

Refs #362.

* chore(track): finalize cli-default-experimental-api-20260430

- Move active/ -> completed/
- Update metadata.json: status -> review, pr -> #363
- Sync tracks.jsonl section + status
- Add product spec SPEC-001 (deployment) merged from track spec
- Update product-specs index

* fix: apply AI code review suggestions

- config: trim vercel-args before mutual-exclusion check; whitespace-only
  values no longer trigger spurious errors and the trimmed value is what
  gets stored in the cli variant (copilot review thread)
- config: resolveDeploymentEnvironment now takes the parsed DeploymentMode
  and the typed target; in experimental-api mode the GitHub deployment
  environment is inferred from target=production rather than from
  vercel-args (which is forbidden in that mode). Fixes a mislabel where
  API-mode production deploys appeared as preview in GitHub deployments.
  (copilot + cubic review threads)
- vercel: add an exhaustive default branch with assertNever in
  createVercelClient() so unexpected deployment.kind values fail loud
  at runtime instead of silently returning undefined (copilot review)
- README: close the scope row in the inputs table with a trailing |
  (cubic review)
- plan.md: correct the historical 244 -> 243 unit test count
  (cubic review). 248 today after the new tests added in this commit.
- tests: cover trimmed vercel-args, target-aware experimental-api
  environment resolution, and the new resolveDeploymentEnvironment
  signature in index.test.ts

Refs #362.

Author: amondnet

.please/docs/knowledge/product.md

@@ -13,11 +13,12 @@ Provide the most reliable and feature-rich GitHub Action for automating Vercel d
 ## Core Features
 
 1. **Vercel Deployment** — Execute Vercel CLI deployments (preview and production) from GitHub Actions
-2. **PR & Commit Comments** — Automatically comment deployment URLs on pull requests and commits
-3. **GitHub Deployments** — Create GitHub Deployment records with environment tracking, status updates, and auto-deactivation
-4. **Alias Domains** — Assign custom domains to deployments with template variables (PR number, branch name)
-5. **Backward Compatibility** — Maintain support for legacy "zeit-" prefixed inputs
-6. **Flexible Configuration** — Support working directories, team scopes, custom CLI arguments, and project name overrides
+2. **Experimental API Mode** — Opt-in deployment via `@vercel/client` (gated by `experimental-api: true`) for projects that prefer typed action inputs over CLI passthrough; mutually exclusive with `vercel-args`
+3. **PR & Commit Comments** — Automatically comment deployment URLs on pull requests and commits
+4. **GitHub Deployments** — Create GitHub Deployment records with environment tracking, status updates, and auto-deactivation
+5. **Alias Domains** — Assign custom domains to deployments with template variables (PR number, branch name)
+6. **Backward Compatibility** — Maintain support for legacy "zeit-" prefixed inputs
+7. **Flexible Configuration** — Support working directories, team scopes, custom CLI arguments, and project name overrides
 
 ## Success Metrics
 

.please/docs/product-specs/deployment/spec.md

@@ -0,0 +1,114 @@
+---
+id: SPEC-002
+level: V_M
+domain: deployment
+feature: spec
+depends: []
+conflicts: []
+traces: []
+created_at: 2026-04-30T00:58:55Z
+updated_at: 2026-04-30T00:58:55Z
+source_tracks: ["cli-default-experimental-api-20260430"]
+---
+
+# Deployment Mode Specification
+
+## Purpose
+
+Defines how the action selects and runs a Vercel deployment. The default path is the stable Vercel CLI; an opt-in experimental API path using `@vercel/client` is available for users who accept the risk of an internal Vercel package without semver guarantees.
+
+## Requirements
+
+### Requirement: experimental-api input
+
+The system MUST expose an `experimental-api` boolean action input that defaults to `false`.
+
+#### Scenario: experimental-api input
+
+- GIVEN the action is invoked from a workflow
+- WHEN the user does not set `experimental-api`
+- THEN the action behaves as if `experimental-api: false` had been set explicitly
+
+### Requirement: CLI is the default deployment client
+
+The system MUST route to the Vercel CLI client (`VercelCliClient`) whenever `experimental-api` is `false` or unset, regardless of whether `vercel-args` is provided.
+
+#### Scenario: CLI is the default deployment client
+
+- GIVEN `experimental-api` is `false` or unset
+- WHEN the action selects a deployment client
+- THEN it returns `VercelCliClient` and logs `Using CLI-based deployment`
+
+### Requirement: experimental API opt-in with warning
+
+The system MUST route to the API client (`VercelApiClient`) only when `experimental-api` is `true`, and MUST emit a single `core.warning` per run stating that API mode is experimental and may break across `@vercel/client` updates.
+
+#### Scenario: experimental API opt-in with warning
+
+- GIVEN `experimental-api` is `true`
+- WHEN the action selects a deployment client
+- THEN it returns `VercelApiClient` and emits exactly one `core.warning` referencing `@vercel/client` and the experimental nature
+
+### Requirement: mutual exclusion of experimental-api and vercel-args
+
+The system MUST fail fast at config-parse time with a clear error naming both inputs when `experimental-api` is `true` and `vercel-args` is non-empty.
+
+#### Scenario: mutual exclusion of experimental-api and vercel-args
+
+- GIVEN `experimental-api: true` and `vercel-args: --prod` are both set
+- WHEN the action parses inputs
+- THEN it throws a configuration error before any deployment side effects, mentioning both `experimental-api` and `vercel-args`
+
+### Requirement: legacy vercel-args passthrough preserved
+
+The system MUST honor the existing `vercel-args` CLI passthrough when `experimental-api` is `false`, routing to `VercelCliClient` and forwarding the args verbatim.
+
+#### Scenario: legacy vercel-args passthrough preserved
+
+- GIVEN `experimental-api` is `false` and `vercel-args` contains a non-empty string
+- WHEN the action runs
+- THEN `VercelCliClient` is constructed and the provided args are passed to the underlying `vercel` CLI invocation
+
+### Requirement: typed config carries the deployment mode
+
+The system MUST surface the deployment mode on `ActionConfig` as a discriminated union (`{ kind: 'cli', vercelArgs }` or `{ kind: 'experimental-api' }`) so that the (`experimental-api`, `vercel-args`) mutual-exclusion is unrepresentable at the type level.
+
+#### Scenario: typed config carries the deployment mode
+
+- GIVEN `getActionConfig()` parses raw action inputs
+- WHEN the parsing succeeds
+- THEN the returned `ActionConfig.deployment` is exactly one variant of the union and the variant matches the user's input
+
+### Requirement: action.yml input metadata is accurate
+
+The system MUST keep `action.yml` input descriptions and deprecation messages aligned with the current routing semantics — `vercel-args` and `scope` are not deprecated under the CLI-default model, while legacy `zeit-*` / `now-*` inputs remain deprecated.
+
+#### Scenario: action.yml input metadata is accurate
+
+- GIVEN a user reads `action.yml` in their editor or browser
+- WHEN they look at `vercel-args`, `scope`, and `experimental-api`
+- THEN each has a meaningful description, no misleading deprecation copy on `vercel-args` / `scope`, and the `experimental-api` description names the mutual-exclusion rule
+
+### Requirement: README documents the deployment mode
+
+The system MUST provide README documentation that explains the CLI default, the `experimental-api` opt-in, the experimental warning, the mutual-exclusion rule, and a migration note for users coming from the previous API-default behavior.
+
+#### Scenario: README documents the deployment mode
+
+- GIVEN a user opens README.md to learn how to deploy
+- WHEN they read the "Deployment Mode" section
+- THEN they see CLI documented as the default, `experimental-api: true` documented as the opt-in, the warning text quoted, the mutual-exclusion rule stated, and a migration note for previous v42 users
+
+## Non-functional Requirements
+
+### Requirement: behavior parity for API mode outputs
+
+The system SHOULD preserve deployment output parity (`preview-url`, `preview-name`, `deployment-id`) between API mode and the previous API-default behavior whenever `experimental-api: true` is set.
+
+### Requirement: semver MINOR release for the routing change
+
+The system SHOULD ship the routing-default change as a semver MINOR release. No public API contract is broken; only default behavior shifts. The migration is documented in release notes and the README.
+
+### Requirement: test coverage for routing and config parsing
+
+The system SHOULD maintain ≥80% test coverage for the routing factory and the new config-parsing logic, including the four-case routing matrix and the mutual-exclusion error.

.please/docs/product-specs/index.md

@@ -5,3 +5,4 @@
 | Spec | Domain | Feature | Created | Related Tracks |
 |------|--------|---------|---------|----------------|
 | SPEC-001 | deployment | vercel-build | 2026-04-30 | ["auto-vercel-build-20260430"] |
+| SPEC-002 | deployment | spec | 2026-04-30 | ["cli-default-experimental-api-20260430"] |

.please/docs/tracks.jsonl

@@ -3,3 +3,4 @@
 {"id":"build-exit-255-20260423","type":"bugfix","status":"review","phase":"finalize","issue":"#336","pr":"#350","created":"2026-04-23","section":"completed"}
 {"id":"fix-vercel-validation-20260430","type":"bugfix","status":"review","phase":"finalize","issue":"#359","pr":"#364","created":"2026-04-30","section":"completed"}
 {"id":"auto-vercel-build-20260430","type":"feature","status":"review","phase":"finalize","issue":"#360","pr":"#361","created":"2026-04-30","section":"completed"}
+{"id":"cli-default-experimental-api-20260430","type":"feature","status":"review","phase":"finalize","issue":"#362","pr":"#363","created":"2026-04-30","section":"completed"}

.please/docs/tracks/completed/cli-default-experimental-api-20260430/metadata.json

@@ -0,0 +1,11 @@
+{
+  "track_id": "cli-default-experimental-api-20260430",
+  "type": "feature",
+  "status": "review",
+  "created_at": "2026-04-30T00:00:00Z",
+  "updated_at": "2026-04-30T01:00:00Z",
+  "issue": "#362",
+  "pr": "#363",
+  "project": "",
+  "project_item_id": ""
+}