feat(quickstart): add RTC video-call onboarding

CHANGELOG.md

@@ -15,6 +15,14 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [Unreleased]
 
+## [0.2.10] - 2026-09-20
+
+RTC video-call onboarding and package-manager compatibility.
+
+### Added
+
+- Add RTC video-call onboarding to `agora init` and `agora quickstart`, with scenario selection, RTC-only project defaults, workspace readiness checks, and native npm setup commands when the required pnpm version is unavailable ([#69](https://github.com/AgoraIO/cli/pull/69)).
+
 ## [0.2.9] - 2026-08-24
 
 Quickstart project and environment consistency, Android onboarding, Windows installer compatibility, and release workflow maintenance.
@@ -385,7 +393,8 @@ Set `AGORA_ALLOW_UPGRADE_IN_CI=1` only when a CI job intentionally needs to muta
 - Support machine-readable JSON output for automation and agent workflows.
 - Ship automated release packaging through GoReleaser, including cross-platform archives, Linux packages, Homebrew, Scoop, npm wrapper packages, Docker images, and install scripts.
 
-[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.9...HEAD
+[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.10...HEAD
+[0.2.10]: https://github.com/AgoraIO/cli/compare/v0.2.9...v0.2.10
 [0.2.9]: https://github.com/AgoraIO/cli/compare/v0.2.8...v0.2.9
 [0.2.8]: https://github.com/AgoraIO/cli/compare/v0.2.7...v0.2.8
 [0.2.7]: https://github.com/AgoraIO/cli/compare/v0.2.6...v0.2.7

README.md

@@ -135,7 +135,8 @@ Command examples use `agora` for the installed CLI. Local source builds use `./a
 
 | Goal | Command | What You Get |
 |------|---------|--------------|
-| Next.js video app | `agora init my-nextjs-demo --template nextjs` | A cloned Next.js quickstart, `.agora` binding, and `.env.local` |
+| Next.js voice agent | `agora init my-nextjs-demo --template nextjs` | A cloned conversational AI quickstart, `.agora` binding, and `.env.local` |
+| RTC video call | `agora init my-video-demo --template nextjs --scenario video-call` | An RTC-only Next.js quickstart, project binding, and `.env.local` |
 | Python voice agent | `agora init my-python-demo --template python` | A Python quickstart with `server/.env` credentials |
 | Go voice agent | `agora init my-go-demo --template go` | A Go quickstart with `server/.env` credentials |
 | Android voice AI app | `agora init my-android-demo --template android` | An Android client with credentials written only to the included Python server |
@@ -274,6 +275,10 @@ Quickstart template behavior:
 - Python quickstarts copy `server/.env.example` to `server/.env`, then use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE`
 - Go quickstarts copy `server/.env.example` to `server/.env`, then use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE`
 - Existing Python and Go quickstarts keep their recorded env path when reconfigured, while legacy `APP_ID` / `APP_CERTIFICATE` assignments are commented out and replaced with `AGORA_APP_ID` / `AGORA_APP_CERTIFICATE`.
+- The RTC Next.js quickstart reads its pinned pnpm version after clone. Matching
+  pnpm produces reproducible setup steps; otherwise the CLI uses native npm
+  without creating `package-lock.json`. The CLI never installs dependencies or
+  global tools.
 
 `project env write` auto-detects Next.js workspaces (or accepts `--template nextjs|standard`) and writes `AGORA_APP_ID` / `AGORA_APP_CERTIFICATE` or the Next.js equivalents.
 
@@ -306,6 +311,7 @@ It stores durable non-secret metadata:
 - `projectName`
 - `region`
 - `template`
+- `scenario` (when the binding identifies a quickstart scenario)
 - `projectType` (framework hint used for env layout when present)
 - `envPath`
 
@@ -359,7 +365,7 @@ Example:
 
 ```bash
 export AGORA_HOME="$(mktemp -d)"
-agora init my-nextjs-demo --template nextjs --json
+agora init my-nextjs-demo --template nextjs --scenario video-call --json
 agora quickstart create my-python-demo --template python --project my-project --json
 agora quickstart env write my-python-demo --json
 agora project doctor --json

docs/automation.md

@@ -345,11 +345,18 @@ Example:
 ./agora init my-nextjs-demo --template nextjs --json
 ./agora init my-nextjs-demo --template nextjs --new-project --json
 ./agora init my-agent --recipe tool-calling --new-project --json
+./agora init my-video-demo --template nextjs --scenario video-call --new-project --json
 ```
 
 By default `init` reuses an existing project — preferring one named exactly `"Default Project"`. If no default exists, interactive sessions show existing projects with a create-new option and default to the most recently created project; JSON, CI, and non-TTY runs select the most recent project automatically. Pass `--new-project` to force creation. Use `--project <name|id>` to bind to a specific project.
 For deterministic automation, always pass `--project <name|id>` or `--new-project`.
 
+For newly created projects, `init` uses explicit `--feature` values when supplied, replacing the scaffold defaults. Without explicit features, `nextjs + video-call` defaults to `rtc`; existing voice-agent quickstarts and recipes default to `rtc`, `rtm`, and `convoai`. Explicit `convoai` also enables its `rtm` dependency. Unlike `project create --template <preset>`, init does not merge a project preset into the explicit feature list.
+
+When reusing an existing project (explicitly or automatically), `init` does not enable features or require the scaffold's feature list to be enabled before cloning. `--feature` only controls new project creation. Use `project feature enable` to enable features on an existing project, and `project doctor --feature <feature>` to check runtime readiness. Invalid inputs, credential requirements, and scaffold identity checks still apply.
+
+Migration note for RTC onboarding previews: `init` no longer returns `QUICKSTART_REQUIRED_FEATURE_MISSING` for reused projects. Explicit quickstart features now replace scenario creation defaults rather than adding to them. The existing `project create` preset-merging behavior is unchanged.
+
 Required `data` fields:
 - `action`
   Always `init`.
@@ -375,27 +382,43 @@ Required `data` fields:
 - `metadataPath`
   Repo-local project binding file path, currently `.agora/project.json`.
 - `enabledFeatures`
-  Array of features enabled during this run. Defaults to `rtc`, `rtm`, and `convoai` for newly created projects unless overridden with `--feature`. Empty for existing projects since the CLI did not create them in this run.
+  Array of features enabled during this run, using the creation rules above. For example, voice-agent with explicit `--feature rtc` returns only `rtc`, while video-call without explicit features defaults to `rtc`. Empty for reused projects; this field does not enumerate all features already available on the project.
 - `nextSteps`
-  Ordered list of suggested follow-up commands for the selected source.
+  Ordered list of suggested follow-up commands for the selected source. For the RTC Next.js quickstart, these use matching pnpm or a native npm fallback detected after clone.
 - `status`
-  Currently `ready`.
+  Currently `ready`, meaning the scaffold and configuration are prepared; it does not certify that all runtime features are enabled.
 
 Optional fields:
 - `template`
   Present for built-in quickstart initialization.
+- `scenario`, `requiredFeatures`
+  Present for built-in quickstart initialization; describe the selected scenario and its runtime requirements. `requiredFeatures` is not an initialization gate or a list of features enabled during this run.
 - `recipe`, `recipeUrl`, `recipeRawUrl`, `primaryPrompt`, `cloneUrl`
   Present for recipe-backed initialization. The CLI resolves this metadata from
   the official recipes API before it selects or creates a project.
 - `rtmDataCenter`
   RTM data center configured on the new project when RTM was enabled. Defaults to `NA` when `--rtm-data-center` is omitted.
+- `packageManager`
+  Present when the selected quickstart exposes a supported pinned package manager.
+  Existing fields are `name`, `requiredVersion`, optional `detectedVersion`,
+  `strategy` (`native`, `npm`, or `unavailable`), `ready`, and optional
+  `message`. `selectedName` and `selectedVersion` identify the command runner
+  used by the resolved steps.
 
 Display-oriented fields:
 - `title`
 
 Safe branch fields:
 - `sourceType`
 - `sourceId`
+- `template`
+- `scenario`
+- `requiredFeatures`
+- `packageManager.name`
+- `packageManager.requiredVersion`
+- `packageManager.strategy`
+- `packageManager.ready`
+- `packageManager.selectedName`
 - `projectAction`
 - `projectId`
 - `path`
@@ -414,6 +437,7 @@ Example:
 ./agora project create my-agent-demo --json
 ./agora project create my-agent-demo --rtm-data-center EU --json
 ./agora project create my-agent-demo --feature rtc --feature convoai --json
+./agora project create my-video-demo --template video-call --json
 ```
 
 Required `data` fields (success):
@@ -424,7 +448,9 @@ Required `data` fields (success):
 - `appId`
 - `region`
 - `enabledFeatures`
-  Array of features that were enabled on the new project. Defaults to `["rtc", "rtm", "convoai"]` when no `--feature` flags are passed. Explicit `convoai` requests also include `rtm`.
+  Array of features that were enabled on the new project. With `--template video-call`, starts with `["rtc"]`; with `--template voice-agent`, starts with `["rtc", "rtm", "convoai"]`. Explicit `--feature` values are added to the preset's required features. Without a preset, explicit features are used, or `["rtc", "rtm", "convoai"]` when none are specified. Requests containing `convoai` also include `rtm`.
+- `template`
+  Project preset applied (`video-call` or `voice-agent`), or an empty string when not requested.
 
 Optional fields:
 - `rtmDataCenter`
@@ -653,6 +679,9 @@ Required `data` fields:
 
 Each item currently includes:
 - `id`
+- `template`
+- `scenario`
+- `requiredFeatures`
 - `title`
 - `description`
 - `runtime`
@@ -661,9 +690,14 @@ Each item currently includes:
 - `available`
 - `envDocs`
 - `supportsInit`
+- `installCommand`
+- `runCommand`
 
 Safe branch fields:
 - `items[].id`
+- `items[].template`
+- `items[].scenario`
+- `items[].requiredFeatures`
 - `items[].runtime`
 - `items[].repoUrl`
 - `items[].available`
@@ -680,6 +714,15 @@ Display-oriented fields:
 Automation notes:
 - `--ref <branch|tag|ref>` pins the cloned quickstart source for workshops and reproducible demos.
 - `--template-only` explicitly skips project lookup and env-file creation. Without a resolved project or this flag, non-interactive runs fail with `QUICKSTART_PROJECT_REQUIRED` before cloning.
+- `--scenario <scenario>` selects an exact scenario; when omitted, the template's default scenario is used.
+- `nextjs + video-call` requires only `rtc` and honors `AGORA_QUICKSTART_NEXTJS_VIDEO_CALL_REPO_URL` for local mirrors and fixtures.
+- Non-default scenarios such as `nextjs + video-call` must provide `agora.quickstart.json` with matching `template` and `scenario`. The CLI validates it after clone and removes the target before writing env or binding data when validation fails. Existing default-scenario quickstarts remain compatible without a manifest.
+- After cloning `nextjs + video-call`, the CLI reads `package.json#packageManager`.
+  An exact pnpm match produces `pnpm install --frozen-lockfile` and `pnpm dev`.
+  Missing or mismatched pnpm produces `npm install --package-lock=false` and
+  `npm run dev` when npm is available. If neither is available,
+  `packageManager.ready` is false and no unusable
+  install or run command is included in `nextSteps`.
 
 Example:
 
@@ -691,6 +734,8 @@ Required `data` fields:
 - `action`
   Always `create`.
 - `template`
+- `scenario`
+- `requiredFeatures`
 - `title`
 - `runtime`
 - `cloneUrl`
@@ -711,9 +756,22 @@ Required `data` fields:
 Optional fields:
 - `projectId`
 - `projectName`
+- `packageManager`
+  Present for RTC Next.js when `package.json#packageManager` is a strict
+  `pnpm@<major>.<minor>.<patch>` value. Its fields are `name`,
+  `requiredVersion`, optional `detectedVersion`, `strategy`, `ready`, and an
+  optional diagnostic `message`. `selectedName` and `selectedVersion` identify
+  the package manager used by the resolved steps.
 
 Safe branch fields:
 - `template`
+- `scenario`
+- `requiredFeatures`
+- `packageManager.name`
+- `packageManager.requiredVersion`
+- `packageManager.strategy`
+- `packageManager.ready`
+- `packageManager.selectedName`
 - `path`
 - `envStatus`
 - `envPath`
@@ -737,6 +795,8 @@ Required `data` fields:
 - `action`
   Always `env-write`.
 - `template`
+- `scenario`
+- `requiredFeatures`
 - `title`
 - `path`
   Absolute path to the quickstart root.
@@ -750,6 +810,9 @@ Required `data` fields:
   Currently `created`, `updated`, or `appended`.
 
 Env write behavior:
+- for an existing workspace, omitted template/scenario fields are inherited from `.agora/project.json` and `agora.quickstart.json`; only fields absent from both sources fall back to detection or the template default
+- `--template nextjs` alone does not change a recorded `video-call` scenario to `voice-agent`; legacy bindings without a scenario can inherit it from the manifest
+- conflicting nonempty template/scenario declarations fail with `QUICKSTART_SELECTION_MISMATCH` before changing env or binding files
 - quickstart env files contain only the App ID and App Certificate variable names required by the template
 - Next.js uses `NEXT_PUBLIC_AGORA_APP_ID` and `NEXT_AGORA_APP_CERTIFICATE`
 - Python and Go use `AGORA_APP_ID` and `AGORA_APP_CERTIFICATE`
@@ -760,6 +823,8 @@ Env write behavior:
 
 Safe branch fields:
 - `template`
+- `scenario`
+- `requiredFeatures`
 - `path`
 - `envPath`
 - `projectId`
@@ -804,6 +869,12 @@ Safe branch fields:
 - `blockingIssues`
 - `warnings`
 
+Deep workspace checks:
+- Recipe bindings are not validated against built-in quickstart layouts. They return a `WORKSPACE_TEMPLATE_UNKNOWN` warning explaining that recipe runtime/env checks are not covered. Generic project and binding identity checks still run.
+- An unrecognized directory without a declared quickstart also produces a warning, not a template blocking issue.
+- With no other issues, these cases return `healthy: true`, `status: "warning"`, `ok: false`, and exit code `2`. This means no blocking issue was found, not that the workspace was fully verified.
+- Invalid declared quickstarts, required manifests, selection conflicts, and project/credential mismatches remain blocking. A workspace warning does not remove an existing blocking issue.
+
 Recommended agent behavior:
 - branch first on `status`
 - use `healthy` as a fast readiness boolean

docs/commands.md

@@ -108,11 +108,12 @@ Create a project and initialize an official quickstart or recipe
 |------|------|---------|-------------|
 | `--add-agent-rules` | `stringArray` | `[]` | write AI agent rules into the quickstart (repeatable: cursor, claude, windsurf) |
 | `--dir` | `string` | — | target directory for the cloned quickstart; defaults to <name> |
-| `--feature` | `stringArray` | `[]` | enable a feature on the newly created project (repeatable); defaults to rtc, rtm, convoai; convoai also enables rtm |
+| `--feature` | `stringArray` | `[]` | select features for new projects (repeatable); explicit values override scenario defaults; omitted uses scenario defaults; ignored when reusing a project; convoai also enables rtm |
 | `--new-project` | `bool` | — | always create a new Agora project instead of reusing an existing one |
 | `--project` | `string` | — | existing project ID or exact project name to bind to |
 | `--recipe` | `string` | — | official Agora recipe slug (run agora recipes list to discover slugs) |
 | `--rtm-data-center` | `string` | — | RTM data center to configure when rtm is enabled on a newly created project (CN, NA, EU, or AP); defaults to NA |
+| `--scenario` | `string` | — | quickstart scenario; omitted selects the template default |
 | `--template` | `string` | — | quickstart template ID to use |
 
 ### `agora introspect`
@@ -174,7 +175,7 @@ Create a new remote Agora project
 | `--feature` | `stringArray` | `[]` | enable one or more features after creation; defaults to rtc, rtm, convoai; convoai also enables rtm |
 | `--idempotency-key` | `string` | — | caller-provided key for safe retries when supported by the API |
 | `--rtm-data-center` | `string` | — | RTM data center to configure when rtm is enabled (CN, NA, EU, or AP); defaults to NA |
-| `--template` | `string` | — | apply a higher-level project preset such as voice-agent |
+| `--template` | `string` | — | apply a project scenario preset: video-call, voice-agent |
 
 ### `agora project doctor`
 
@@ -333,6 +334,7 @@ Clone an official Agora quickstart into a new directory
 | `--dir` | `string` | — | target directory for the cloned quickstart; defaults to <name> |
 | `--project` | `string` | — | project ID or exact project name to use for env seeding |
 | `--ref` | `string` | — | git branch, tag, or ref to clone for pinned workshops |
+| `--scenario` | `string` | — | quickstart scenario; omitted selects the template default |
 | `--template` | `string` | — | quickstart template ID from `agora quickstart list` |
 | `--template-only` | `bool` | — | clone without resolving a project or writing credentials |
 
@@ -349,6 +351,7 @@ Write the quickstart env file for the current or selected project
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
 | `--project` | `string` | — | project ID or exact project name to use for env seeding |
+| `--scenario` | `string` | — | quickstart scenario; if omitted, use binding, manifest, or the template default |
 | `--template` | `string` | — | quickstart template ID; if omitted, the CLI detects it from the repo layout |
 
 ### `agora quickstart list`
@@ -461,4 +464,10 @@ Show the current auth status
 
 **`doctorStatus`**: `healthy`, `warning`, `not_ready`, `auth_error`
 
+**`projectTemplates`**: `video-call`, `voice-agent`
+
+**`quickstartScenarios`**: `voice-agent`, `video-call`
+
+**`quickstartTemplates`**: `nextjs`, `python`, `go`, `android`
+
 **`recipeTypes`**: `all`, `ai`, `rtc`