dsh-agora 0.2.0

package/assets/agora/references/cli/doctor.md

@@ -0,0 +1,129 @@
+# Agora CLI Doctor
+
+<!-- applies-from: v0.2.1 -->
+
+Use this file when the user needs either local CLI install diagnostics (`agora doctor`) or project readiness diagnostics (`agora project doctor`).
+
+Verified against Agora CLI `0.2.1`.
+
+> **Agents:** run [CLI readiness](README.md#cli-readiness-agents) before doctor-driven recovery loops.
+
+## Purpose
+
+`agora doctor` checks the local CLI install.
+
+`agora project doctor` checks whether a project is control-plane ready for feature development from the CLI's point of view.
+
+Use `agora doctor` first when the failure looks local to the workstation or shell. Use `agora project doctor` when auth works and the problem is project configuration or feature readiness.
+
+## Install Doctor
+
+Top-level `agora doctor` is available in `0.2.0+`. For `0.1.7–0.1.x`, use the read-only version and PATH checks in [CLI readiness](README.md#cli-readiness-agents), then prefer upgrading to the verified `0.2.1` baseline before deeper diagnostics.
+
+```bash
+agora doctor
+agora doctor --json
+agora doctor --quiet
+```
+
+Verified `0.2.1` install-doctor checks include:
+
+- binary path and PATH resolution
+- installed version
+- `AGORA_HOME` writability
+- API and OAuth DNS/network reachability
+- auth/session state
+- known MCP host detection
+
+Verified `0.2.1` install-doctor exit codes:
+
+- `0`: healthy
+- `1`: blocking install issues
+- `2`: warnings
+- `3`: auth or session issues
+
+Common recovery paths:
+
+- PATH issue: run the shell-specific command printed by `agora doctor`, or use `which -a agora` to find a shadowing old binary. Do not uninstall automatically; ask before removing a stale binary — see [README.md](README.md#cli-readiness-agents)
+- CLI below `0.1.7` or config schema newer than the running binary: follow the curl-first upgrade path in [install-auth.md](install-auth.md#version-gate-and-upgrade)
+- network or DNS issue: fix connectivity or proxy settings before retrying auth
+- auth issue: run `agora login`
+
+It verifies:
+
+- logged-in session
+- project resolution or current-project context
+- feature readiness
+- basic project configuration such as App ID presence
+- in `--deep` mode, repo-local `.agora` metadata and quickstart env consistency checks where applicable
+
+It does not replace the full Conversational AI quickstart, RTM runtime validation, or end-to-end sample validation.
+
+## Commands
+
+```bash
+agora project doctor [project]
+agora project doctor --json
+agora project doctor --feature convoai
+agora project doctor --feature rtc
+agora project doctor --feature rtm
+agora project doctor --deep
+```
+
+## Interpreting Results
+
+Verified result states in `0.2.1`:
+
+- `healthy`: project is ready from the CLI's current checks
+- `warning`: partially ready, but not fully clean
+- `not_ready`: blocking issues were found
+- `auth_error`: not logged in or project context cannot be resolved
+
+Exit behavior verified in `0.2.1`:
+
+- healthy doctor run exits `0`
+- blocking readiness issues exit `1`
+- warning-only readiness issues exit `2`
+- auth or session issues exit `3`
+
+## Common Recovery Commands
+
+If doctor reports an auth problem:
+
+```bash
+agora login
+```
+
+If doctor cannot resolve the target project:
+
+```bash
+agora project use <project>
+```
+
+If doctor reports ConvoAI feature readiness issues:
+
+```bash
+agora project feature enable convoai
+```
+
+If RTM or a related capability was just enabled and the first run still fails, allow bounded wait/retry before concluding the project is still broken. Control-plane enablement may surface before the runtime service is actually usable.
+
+## Deep Mode
+
+`--deep` is part of the verified CLI surface. It runs deeper repo-local checks for `.agora` metadata and quickstart env consistency where applicable.
+
+Do not claim `--deep` proves RTC or RTM runtime connectivity. It remains a CLI readiness check.
+
+## First-Success Boundary
+
+Treat doctor results as **control-plane readiness only**:
+
+- `healthy` / `warning` can mean the project is configured correctly at the CLI layer
+- they do **not** prove RTM is already usable
+- they do **not** prove the official sample can start, open, survive `Try it now`, and complete a conversation
+
+## Fix Mode
+
+`--fix` is not in the verified command surface. Do not claim broad automatic remediation behavior unless a future CLI version documents it.
+
+For safe guidance, prefer explicit remediation commands over "the CLI will fix this automatically."

package/assets/agora/references/cli/env.md

@@ -0,0 +1,158 @@
+# Agora CLI Project Environment Export
+
+<!-- applies-from: v0.2.1 -->
+
+Use this file when the user needs to export project credentials, write dotenv files, or explain the difference between generic project env and quickstart env commands.
+
+Verified against Agora CLI `0.2.1`.
+
+> **Agents:** complete [CLI readiness](README.md#cli-readiness-agents) first. For official quickstarts, **`quickstart env write` is mandatory** — see warning below.
+
+`agora project env` is the CLI's primary generic project-environment export command. Official quickstart repos have a separate template-aware writer: `agora quickstart env write`.
+
+## Critical Agent Rule
+
+Using `agora project env write` on an official Python or Go quickstart writes **`AGORA_APP_ID`** to a generic dotenv path. Those samples read **`APP_ID`** from `server/.env` or `server-go/.env`. The backend starts with empty credentials.
+
+For official quickstarts, always use:
+
+```bash
+agora quickstart env write [repo-path]
+```
+
+Use:
+
+```bash
+agora project env
+```
+
+when the user wants project env vars.
+
+Use:
+
+```bash
+agora project env write [path]
+```
+
+when they explicitly want generic Agora App ID / App Certificate values materialized into a dotenv file.
+
+Use:
+
+```bash
+agora quickstart env write [repo-path]
+```
+
+when working inside an official quickstart or writing template-specific env names such as `NEXT_PUBLIC_AGORA_APP_ID` or `APP_ID`.
+
+## Export Commands
+
+Default behavior:
+
+```bash
+agora project env
+```
+
+This prints non-sensitive dotenv lines to `stdout`. It does not write a file.
+
+Other supported forms:
+
+```bash
+agora project env --shell
+agora project env --json
+agora project env --format dotenv
+agora project env --format shell
+agora project env --format envelope
+agora project env --format json
+agora project env --project <project>
+agora project env --with-secrets
+```
+
+Use cases:
+
+- default dotenv output: paste into `.env`, redirect to a file, or inspect values
+- `--shell`: `source <(agora project env --format shell)`
+- `--json` or `--format envelope`: agents, CI, or scripts using the unified JSON envelope
+- `--project <project>`: export a non-current project without changing local context
+- `--with-secrets`: include sensitive values such as the app certificate
+
+Option rules:
+
+- `--format shell` and `--shell` are equivalent output choices; use one or the other
+- `--format` and `--shell` cannot be combined
+- `--json` and `--shell` cannot be combined
+- invalid `--format` values fail with: `` `--format` must be one of: dotenv, shell, envelope, json ``
+
+## Project Env Variables
+
+The verified `0.2.1` project env export contract focuses on:
+
+- `AGORA_APP_ID`
+- `AGORA_APP_CERTIFICATE` only when `--with-secrets` is provided
+
+Do not invent alternate names for the CLI env contract. If an agent needs project metadata beyond credentials, use `agora project show --json`.
+
+## Secrets Rule
+
+Secrets are opt-in.
+
+- By default, `agora project env` exports only non-sensitive development config.
+- `AGORA_APP_CERTIFICATE` is emitted only with `--with-secrets`.
+- If the target project does not have an app certificate, `--with-secrets` fails instead of silently emitting an empty value.
+
+## Generic Project Env Writing
+
+`agora project env write [path]` writes generic `AGORA_APP_ID` and `AGORA_APP_CERTIFICATE` values to a dotenv file. If the selected project has no App Certificate, env writing cannot seed a token-ready app.
+
+Supported flags:
+
+```bash
+agora project env write
+agora project env write apps/web/.env.local
+agora project env write --append
+agora project env write --overwrite
+agora project env write .env.local --template nextjs
+```
+
+Write rules:
+
+- explicit `path`: write exactly that target path
+- no `path`: choose the best default `.env*` target based on the current project directory
+- `--append`: append App ID and App Certificate values when no existing values are present
+- `--overwrite`: replace the target file with only Agora App ID and App Certificate values
+- `--template nextjs|standard`: override the workspace detector when the credential key layout must be forced
+- do not combine `--append` and `--overwrite`
+
+Ask for explicit approval before running `--overwrite`, and state the target path before writing. Prefer append/update behavior for existing env files.
+
+Do not use template files such as `.env.example`, `.env.sample`, or `.env.template` as write targets for real values or secrets.
+
+In `0.2.1`, `project env write` updates or creates repo-local `.agora/project.json` metadata and records detected `projectType` / `envPath` when missing.
+
+## Quickstart Env Writing
+
+Official quickstarts use template-specific env names and file paths. Use [quickstarts.md](quickstarts.md) for the full flow.
+
+Verified `0.2.1` examples:
+
+```bash
+agora quickstart env write my-python-demo --project my-project
+agora quickstart env write /abs/path/to/my-go-demo --json
+```
+
+Template-specific behavior:
+
+| Template | Target | Variables |
+|---|---|---|
+| Next.js quickstart | `.env.local` | `NEXT_PUBLIC_AGORA_APP_ID`, `NEXT_AGORA_APP_CERTIFICATE` |
+| Python quickstart | `server/.env` | `APP_ID`, `APP_CERTIFICATE` |
+| Go quickstart | `server-go/.env` | `APP_ID`, `APP_CERTIFICATE` |
+
+Existing env files are preserved. The CLI updates existing credential keys, appends missing values, and comments duplicate or stale Agora credential aliases for the selected runtime.
+
+## Agent Guidance
+
+- For raw env consumption, prefer `agora project env --json` over `agora project show --json`.
+- For shell sessions, prefer `agora project env --format shell`.
+- For generic repo setup, use `agora project env write`.
+- For official quickstart repos, use `agora quickstart env write` so the correct file path and variable names are used.
+- `project env` prints the selected format directly; `project env write` and `quickstart env write` are action commands and can be consumed with `--json`.

package/assets/agora/references/cli/install-auth.md

@@ -0,0 +1,152 @@
+# Agora CLI Install and Auth
+
+<!-- applies-from: v0.2.1 -->
+
+Use this file when the user needs to install the Agora CLI, authenticate, or verify that the local install is healthy.
+
+Verified against Agora CLI `0.2.1`.
+
+> **Agents:** start with the read-only **CLI readiness** probe in [README.md](README.md). Installers and global npm installs are allowed only as readiness remediation after user approval. That section is the single source of truth for version gates, curl-first upgrade, PATH recovery, and config mismatch errors.
+
+## Install
+
+Ask for user approval before running installers, global package installs, shell-profile updates, or package removal commands.
+
+## Version Gate and Upgrade
+
+Use [README.md](README.md#cli-readiness-agents) as the canonical agent readiness flow.
+
+- Read-only probe first: `agora version` and `which -a agora` / `where.exe agora`.
+- If `agora` is missing or below `0.1.7`, stop normal CLI workflow and upgrade. Do not call `agora upgrade` on `0.1.6`; it does not exist there.
+- Preferred remediation after approval: `curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh`.
+- Alternate remediation after approval: `npm install -g agoraio-cli` when Node.js 18+ is available.
+- If a direct-installer upgrade from `0.1.7`–`0.2.0` fails crossing `0.2.1`, re-run the curl installer once because release archive names changed.
+- If `agora version` still reports an old version after install, check PATH shadowing with `which -a agora` / `where.exe agora` and follow `agora doctor`'s shell-specific PATH fix when available. Do not uninstall automatically; remove an old binary only after user approval, using `install.sh --uninstall` / `install.ps1 -Uninstall` for installer-managed installs when applicable.
+- If the CLI errors with `Config version N is newer than this CLI supports`, an old binary is usually reading config from a newer CLI. Upgrade through the readiness flow; edit config only as a last resort after backing it up.
+
+Preferred macOS / Linux / POSIX shell installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
+```
+
+Windows PowerShell installer:
+
+```powershell
+irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 | iex
+```
+
+npm install path:
+
+```bash
+npm install -g agoraio-cli
+```
+
+The npm package is expected to be a thin install wrapper for the same Go-based `agora` binary. It requires Node.js 18+ when used. Do not describe npm as a permanent separate CLI implementation.
+
+In `0.2.1`, the shell installers add the binary directory to `PATH` and wire shell completion by default. Use `--no-path`, `--no-completion`, or `--skip-shell` only when the user explicitly wants to opt out.
+
+The installed command is:
+
+```bash
+agora --help
+agora version
+agora doctor --json
+```
+
+If the user still has the deprecated preview package:
+
+```bash
+npm uninstall -g agora-cli-preview
+npm install -g agoraio-cli
+```
+
+For pinned versions, uninstall, custom install directories, Windows details, npm details, or source builds, use the upstream install docs in <https://github.com/AgoraIO/cli>.
+
+> ⚠️ Removed in v0.2.0: `curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --add-to-path`. Use `curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh` instead.
+
+## Login Flow
+
+Primary commands:
+
+```bash
+agora login
+agora login --no-browser
+agora whoami
+agora logout
+```
+
+Equivalent auth-group commands:
+
+```bash
+agora auth login
+agora auth status
+agora auth status --json
+agora auth logout
+```
+
+`agora login` starts an OAuth browser flow and stores a local session.
+
+If browser auto-open fails, use `agora login --no-browser` so the CLI prints a URL and the user can open it manually.
+
+For agents, use `agora auth status --json`. In `0.2.1`, unauthenticated status is still a recoverable auth state; the JSON error envelope uses exit code `3` with `AUTH_UNAUTHENTICATED`.
+
+## Verification and Failure Modes
+
+Run the install self-test before debugging higher-level project issues:
+
+```bash
+agora doctor
+agora doctor --json
+```
+
+Observed `0.2.1` exit codes:
+
+- `0`: healthy install
+- `1`: blocking install issues
+- `2`: warnings
+- `3`: auth or session issues
+
+Common failures:
+
+- If `agora doctor` reports PATH issues, follow the command it prints for the current shell.
+- If `agora doctor` reports DNS or network failures, fix network or proxy settings before retrying `agora login`.
+- If `agora login` is run in JSON, CI, or non-TTY mode without an existing session, `-y` / `--yes` does not start a new browser flow; the command fails fast with `AUTH_UNAUTHENTICATED`.
+- If upgrade from a direct installer fails when crossing 0.2.1, re-run the curl installer once — see [README.md](README.md) CLI readiness.
+
+## OAuth Loopback Rule
+
+The verified `0.2.0` loopback login flow advertises a redirect URI shaped like:
+
+```text
+http://localhost:<port>/oauth/callback
+```
+
+Important rule:
+
+- the `redirect_uri` sent to authorize and token exchange must match exactly
+- treat `localhost` and `127.0.0.1` as different strings for OAuth validation
+
+If the user reports a `redirect_uri mismatch` or a browser login that gets a `400` during token exchange, tell them to check for any local tooling or overrides that switch one step to `127.0.0.1` while the other still uses `localhost`.
+
+## Config and Session Location
+
+The CLI stores config, session, logs, and current-project context under the Agora CLI config directory.
+
+- macOS default: `~/.agora-cli`
+- Linux default: `$XDG_CONFIG_HOME/agora-cli` or `~/.config/agora-cli`
+- local override for testing or isolation: `AGORA_HOME=/custom/path`
+
+## What to Tell the User
+
+- If they are not logged in, tell them to run `agora login` first.
+- If they ask "am I logged in?", use `agora whoami`, `agora whoami --plain`, or `agora auth status --json`.
+- If they ask which environment overrides exist, use `agora env-help --json`.
+- If they want a noninteractive or isolated local setup, route to [automation.md](automation.md).
+
+## Things Not to Overstate
+
+- Do not promise headless service-account auth; the verified flow is browser-based OAuth.
+- Do not document `--add-to-path`; it was removed in `0.2.0`.
+- Do not claim the preview package is still the recommended install target.
+- Use `agora` for an installed CLI. Use `./agora` only when running a local binary built from the CLI repository.

package/assets/agora/references/cli/projects.md

@@ -0,0 +1,116 @@
+# Agora CLI Projects
+
+<!-- applies-from: v0.2.1 -->
+
+Use this file when the user needs to create, select, inspect, or feature-enable Agora projects from the CLI.
+
+Verified against Agora CLI `0.2.1`.
+
+## Core Workflow
+
+Use `agora init` for the fastest end-to-end demo setup. Use low-level project commands when the workflow must be decomposed:
+
+```bash
+agora login
+agora project create my-agent-demo --feature rtc --feature rtm --feature convoai
+agora project use my-agent-demo
+agora project env
+agora project feature list
+agora project list --refresh-cache
+```
+
+## Project Commands
+
+### Create
+
+```bash
+agora project create <name> [--region global|cn] [--template voice-agent] [--feature rtc|rtm|convoai]
+agora project create <name> --dry-run
+agora project create <name> --idempotency-key <key>
+agora project create <name> --rtm-data-center EU
+```
+
+For agent guidance, prefer explicit `--feature` flags because they match the later `project feature` workflow. Omitted `--feature` defaults to `rtc`, `rtm`, and `convoai`, and `convoai` implies `rtm`.
+
+### List
+
+```bash
+agora project list [--page N] [--page-size N] [--keyword <text>]
+agora project list --refresh-cache
+```
+
+Use this when the user needs to discover a project ID or exact project name.
+
+`--refresh-cache` updates the unfiltered first-page cache the CLI uses for shell completion. That matters when the user's completion results lag behind recent project changes.
+
+### Select Current Project
+
+```bash
+agora project use <project>
+```
+
+`<project>` can be a project ID or exact project name.
+
+After `project use`, commands like `project show`, `project feature list`, and `project doctor` can run without repeating the project argument.
+
+### Show One Project
+
+```bash
+agora project show [project]
+agora project show --json
+```
+
+This is the quickest way to inspect App ID, App Certificate, region, sign key, and token-enabled status for the current project.
+
+Use `project show --json` for project metadata inspection.
+
+If the user wants exported env vars or a dotenv workflow, route to [env.md](env.md) and use:
+
+```bash
+agora project env
+agora project env --json
+agora project env write
+```
+
+## Feature Commands
+
+Valid verified feature names:
+
+- `rtc`
+- `rtm`
+- `convoai`
+
+Commands:
+
+```bash
+agora project feature list [project]
+agora project feature status <feature> [project]
+agora project feature enable <feature> [project]
+```
+
+Most ConvoAI onboarding preparation starts with:
+
+```bash
+agora project feature enable convoai
+```
+
+## Current-Project Context
+
+If the user omits `[project]`, the CLI uses the locally selected project context.
+
+In a bound quickstart repo, project resolution prefers repo-local `.agora/project.json` before global `agora project use` context. See [quickstarts.md](quickstarts.md) for the full precedence.
+
+If no project is selected, the verified recovery is:
+
+```bash
+agora project use <project>
+```
+
+or rerun the command with a project argument.
+
+## Things Not to Hallucinate
+
+- Do not invent `agora project delete`.
+- Do not invent `agora project feature disable`.
+- Do not invent ConvoAI-specific nested groups under `agora project`.
+- Do not invent `agora project doctor all`; use `agora project doctor --feature convoai`, `--feature rtc`, or `--feature rtm`.

package/assets/agora/references/cli/quickstarts.md

@@ -0,0 +1,117 @@
+# Agora CLI Init and Quickstarts
+
+<!-- applies-from: v0.2.1 -->
+
+Use this file when the user wants `agora init`, `agora quickstart ...`, or repo-local project binding for an official quickstart.
+
+Verified against Agora CLI `0.2.1`.
+
+> **Agents:** complete [CLI readiness](README.md#cli-readiness-agents) in [README.md](README.md) before any command here.
+
+## Core Decision
+
+Use:
+
+```bash
+agora init <name> --template <template>
+```
+
+when the user wants a new runnable demo with project binding and env writing handled by the CLI.
+
+Use:
+
+```bash
+agora quickstart create <name> --template <template> --project <project>
+agora quickstart env write <path-or-repo> --project <project>
+```
+
+when the user wants to clone or re-bind an official quickstart separately from project creation.
+
+Use low-level `agora project ...` commands when the workflow must be decomposed, resumed, or inspected step by step.
+
+## Commands
+
+```bash
+agora init my-nextjs-demo --template nextjs
+agora init my-python-demo --template python
+agora init my-go-demo --template go
+agora init my-demo --template python --project my-existing-project
+agora init my-demo --template python --new-project
+agora init my-rtm-demo --template nextjs --new-project --feature rtc --feature rtm --rtm-data-center AP
+agora init my-app --template nextjs --add-agent-rules cursor
+```
+
+Agent-safe non-interactive example:
+
+```bash
+agora init my-python-demo --template python --new-project --json
+```
+
+`agora init` creates or binds an Agora project, clones the selected quickstart, writes its env file, persists repo-local project context, and prints next steps. Newly created projects default to `rtc`, `rtm`, and `convoai`; `convoai` also implies `rtm`.
+
+In `--json`, `--yes`, CI, or non-TTY runs, **`--template` is required**. Without it the CLI fails fast with `QUICKSTART_TEMPLATE_REQUIRED`. Do not run bare `agora init <name>` in agent terminals — interactive template prompts cannot be answered there.
+
+```bash
+agora quickstart list
+agora quickstart list --details
+agora quickstart list --show-all
+agora quickstart create my-python-demo --template python --project my-project
+agora quickstart env write my-python-demo --project my-project
+agora quickstart env write /abs/path/to/my-python-demo --json
+```
+
+`quickstart create` shells out to `git clone`. Clone subprocesses disable git credential helpers so agent and CI runs do not hang on macOS keychain prompts.
+
+Typed clone failures:
+
+| Code | Recovery |
+|------|----------|
+| `QUICKSTART_GIT_MISSING` | Install `git` and retry |
+| `QUICKSTART_REF_INVALID` | Pass a valid `--ref` (no leading `-`) |
+| `QUICKSTART_REPO_OVERRIDE_INVALID` | Fix or unset `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL` |
+
+> ⚠️ Removed in v0.2.0: `agora quickstart list --verbose`. Use `agora quickstart list --details` instead.
+
+## Project Binding
+
+The CLI writes repo-local non-secret project metadata to:
+
+```text
+.agora/project.json
+```
+
+Resolution order:
+
+1. explicit `--project` or positional project argument
+2. repo-local `.agora/project.json` resolved from the target repo path
+3. global context set by `agora project use`
+
+`.agora/project.json` can include durable metadata such as project ID, project name, region, template, env path, and detected `projectType`. Do not put secrets in this file.
+
+## Env Writing
+
+`quickstart env write` is template-aware. It writes the variable names and env file path the selected official quickstart expects:
+
+| Template | Target | Variables |
+|---|---|---|
+| Generic project env | selected dotenv file | `AGORA_APP_ID`, `AGORA_APP_CERTIFICATE` |
+| Next.js quickstart | `.env.local` | `NEXT_PUBLIC_AGORA_APP_ID`, `NEXT_AGORA_APP_CERTIFICATE` |
+| Python quickstart | `server/.env` | `APP_ID`, `APP_CERTIFICATE` |
+| Go quickstart | `server-go/.env` | `APP_ID`, `APP_CERTIFICATE` |
+
+**Agent rule:** for official quickstarts, always use **`agora quickstart env write`**, not `agora project env write`. Using the generic writer leaves Python samples with `AGORA_APP_ID` while the backend reads `APP_ID` — the service starts but credentials are empty.
+
+Existing `.env` and `.env.local` files are preserved. The CLI updates existing credential keys, appends missing credentials, and comments duplicate or stale Agora credential aliases for the selected runtime.
+
+Use [env.md](env.md) for generic `agora project env` and `agora project env write` behavior.
+
+## Agent Guidance
+
+- Complete [CLI readiness](README.md#cli-readiness-agents) before `init` or env writes.
+- Prefer `agora init <name> --template <template> --json` for one-shot onboarding.
+- Always pass `--template` in agent, CI, and `--json` runs.
+- Prefer `agora quickstart env write ... --json` when seeding or re-syncing official quickstart repos.
+- Do not substitute manual `git clone` until `init` / `quickstart create` fails with a documented error code and recovery is exhausted.
+- Use `agora project doctor --json` after binding to check control-plane readiness, but do not treat it as proof that the sample can run end to end.
+- Use `agora doctor --json` when available (`0.2.0+`) and the failure looks local to the CLI install rather than to the project.
+- Use `agora` in user-facing commands for an installed CLI. Use `./agora` only when running a local binary built from the CLI repository.