diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 67c7355..d4931f6 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -18,7 +18,7 @@ body:
     attributes:
       label: CLI version
       description: Output of `agora --version`
-      placeholder: "e.g. agora-cli 0.2.0 (commit abc1234, built 2026-05-05)"
+      placeholder: "e.g. agora-cli 0.2.1 (commit abc1234, built 2026-05-20)"
     validations:
       required: true
 
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 1e52270..22c3866 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -10,5 +10,5 @@ contact_links:
     url: https://console.agora.io
     about: Manage your Agora account, projects, and credentials.
   - name: Agora CLI documentation
-    url: https://github.com/AgoraIO/cli/tree/main/agora-cli-go/docs
+    url: https://github.com/AgoraIO/cli/tree/main/docs
     about: Installation, automation, error code catalog, and JSON envelope reference.
diff --git a/.github/workflows/apt-repo.yml b/.github/workflows/apt-repo.yml
index 342c787..07144d8 100644
--- a/.github/workflows/apt-repo.yml
+++ b/.github/workflows/apt-repo.yml
@@ -39,7 +39,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Install apt tools
         run: sudo apt-get install -y --no-install-recommends dpkg-dev apt-utils
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5d6eda7..dcbeb82 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -25,7 +25,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -136,7 +136,7 @@ jobs:
           download_dir="$fixture_root/download/v${version}"
           install_dir="$PWD/.tmp/install-bin"
           bad_install_dir="$PWD/.tmp/install-bin-bad"
-          archive="agora-cli-go_v${version}_${goos}_${goarch}.tar.gz"
+          archive="agora-cli_v${version}_${goos}_${goarch}.tar.gz"
 
           rm -rf "$fixture_root" "$install_dir" "$bad_install_dir"
           mkdir -p "$download_dir"
@@ -191,7 +191,7 @@ jobs:
           $downloadDir = Join-Path $fixtureRoot "download/v$version"
           $installDir = Join-Path $PWD '.tmp/install-bin'
           $badInstallDir = Join-Path $PWD '.tmp/install-bin-bad'
-          $archive = "agora-cli-go_v$version" + "_windows_${arch}.zip"
+          $archive = "agora-cli_v$version" + "_windows_${arch}.zip"
 
           Remove-Item -Recurse -Force $fixtureRoot, $installDir, $badInstallDir -ErrorAction SilentlyContinue
           New-Item -ItemType Directory -Force -Path $downloadDir | Out-Null
diff --git a/.github/workflows/govulncheck.yml b/.github/workflows/govulncheck.yml
index 925cea5..a029bc2 100644
--- a/.github/workflows/govulncheck.yml
+++ b/.github/workflows/govulncheck.yml
@@ -19,7 +19,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Go
         uses: actions/setup-go@v5
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 2007bd1..c1798b1 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -28,7 +28,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -70,5 +70,5 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 95a1ef7..ed4dc9f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -28,7 +28,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0   # GoReleaser needs full history for changelog
 
@@ -57,13 +57,13 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -107,10 +107,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "20"
           registry-url: "https://registry.npmjs.org"
@@ -159,7 +159,7 @@ jobs:
           set -euo pipefail
           mkdir -p dist
           gh release download "${{ steps.ver.outputs.tag }}" \
-            --pattern "agora-cli-go_*" \
+            --pattern "agora-cli_*" \
             --pattern "checksums.txt" \
             --dir dist
           echo "Downloaded artifacts:"
@@ -183,7 +183,7 @@ jobs:
             file="$(echo "$line" | awk '{print $2}')"
             # Only verify our archive files (not e.g. .deb/.rpm we don't repackage).
             case "$file" in
-              agora-cli-go_*_linux_*.tar.gz|agora-cli-go_*_darwin_*.tar.gz|agora-cli-go_*_windows_*.zip) ;;
+              agora-cli_*_linux_*.tar.gz|agora-cli_*_darwin_*.tar.gz|agora-cli_*_windows_*.zip) ;;
               *) continue ;;
             esac
             if [ ! -f "$file" ]; then
@@ -211,7 +211,7 @@ jobs:
           stage_platform() {
             local goos="$1" goarch="$2" npm_pkg="$3" bin_name="$4" archive_ext="$5"
             local pkg_dir="packaging/npm/${npm_pkg}"
-            local archive="agora-cli-go_${tag}_${goos}_${goarch}.${archive_ext}"
+            local archive="agora-cli_${tag}_${goos}_${goarch}.${archive_ext}"
 
             mkdir -p "${pkg_dir}/bin"
             if [ "$archive_ext" = "zip" ]; then
diff --git a/.goreleaser.yaml b/.goreleaser.yaml
index bef7410..8f21dc2 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -20,16 +20,15 @@ builds:
       - -trimpath
     ldflags:
       - -s -w
-      - -X github.com/agora/cli-workspace/agora-cli-go/internal/cli.version={{ .Version }}
-      - -X github.com/agora/cli-workspace/agora-cli-go/internal/cli.commit={{ .ShortCommit }}
-      - -X github.com/agora/cli-workspace/agora-cli-go/internal/cli.date={{ .Date }}
+      - -X github.com/AgoraIO/cli/internal/cli.version={{ .Version }}
+      - -X github.com/AgoraIO/cli/internal/cli.commit={{ .ShortCommit }}
+      - -X github.com/AgoraIO/cli/internal/cli.date={{ .Date }}
 
-# Preserve existing archive naming so install scripts (and future package managers)
-# continue to work without changes.
+# Archive naming matches install.sh, install.ps1, and agora upgrade self-update.
 archives:
   - id: agora-cli
     ids: [agora-cli]
-    name_template: 'agora-cli-go_{{ .Tag }}_{{ .Os }}_{{ .Arch }}'
+    name_template: 'agora-cli_{{ .Tag }}_{{ .Os }}_{{ .Arch }}'
     formats:
       - tar.gz
     format_overrides:
diff --git a/AGENTS.md b/AGENTS.md
index 4d4d85d..f740631 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -200,6 +200,7 @@ When adding a command:
 4. Add the command to the README command model
 5. Add a stable JSON result shape to `docs/automation.md`
 6. Call out breaking JSON or exit-code changes in `CHANGELOG.md` and migration notes in `docs/automation.md` when behavior is intentional.
+7. If the command is exposed through MCP, update `mcpTools()` and refresh the compact tool-surface summary in `docs/llms.txt`.
 
 ## CI and Release
 
@@ -209,7 +210,7 @@ When adding a command:
 | `release.yml` | `v*` tag | Builds cross-platform binaries, publishes GitHub release and package channels |
 | `apt-repo.yml` | published release | Updates the signed apt repository |
 
-Tagging `v0.2.0` (or any `v*` semver tag) triggers the release workflow automatically.
+Tagging `v0.2.1` (or any `v*` semver tag) triggers the release workflow automatically.
 
 ## Gotchas
 
@@ -219,7 +220,8 @@ Tagging `v0.2.0` (or any `v*` semver tag) triggers the release workflow automati
 | Headless OAuth | Use `--no-browser` to print a URL instead of opening a browser |
 | `quickstart env write` ≠ `project env write` | Template-aware paths and variable names vs generic dotenv block |
 | `add` namespace | Reserved and hidden; must behave as not-found from the user's perspective |
-| `doctor --deep` | Flag exists but deep checks are not fully implemented; don't document as stable yet |
+| `doctor --deep` | Stable workspace checks for `.agora` metadata and quickstart env consistency; prefer `--deep --json` in repo-bound automation. |
+| `open` browser launch | Auto-open happens only in interactive pretty TTY sessions outside CI. Use `--browser` to force opening or `--no-browser` for URL-only behavior. |
 | App certificate required | `quickstart env write` and `init` fail env injection if the project has no certificate |
 
 ## npm Distribution (Node Wrapper)
@@ -248,7 +250,7 @@ packaging/npm/
 3. If the platform package is missing, the shim prints a helpful error pointing to Homebrew or GitHub releases
 
 **Release flow (automated and active):** the `publish-npm` job in `release.yml`:
-1. Downloads release archives and `checksums.txt` from the GitHub release
+1. Downloads release archives (`agora-cli_v*`, v0.2.1+) and `checksums.txt` from the GitHub release
 2. Verifies SHA-256 of every archive against `checksums.txt`; fails the job on mismatch
 3. Extracts the binary for each platform into the corresponding package's `bin/`
 4. Stamps the tag version into all `package.json` files (wrapper + 6 platform packages, including `optionalDependencies` values)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b2a9258..780299d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,67 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-20
+
+Automation hardening, quickstart reliability fixes, agent introspection and MCP progress improvements, and release-artifact rename.
+
+### Added
+
+- Emit a `clone:override` progress event when `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL` overrides the clone URL, so workshop and CI runs can confirm which fork they cloned.
+- Document `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL` in `agora env-help` and the automation reference.
+- Add MCP `notifications/progress` forwarding for long-running tools when clients pass `_meta.progressToken`.
+- Add `headlessSafe` and `interactivity` metadata to `agora introspect --json` command records.
+- Add automation contract tests for representative `docs/automation.md` examples.
+
+### Changed
+
+- `agora open` now defaults to URL-only behavior in CI and non-TTY sessions (unless `--browser` is explicitly passed), and adds explicit `--browser` / `--no-browser` conflict validation.
+- `agora init` now requires `--template` in non-interactive (`--yes`) runs instead of silently selecting the first available template; init JSON output now includes `projectSelectionReason` for deterministic agent branching.
+- Block installer-managed `agora upgrade` in CI unless `AGORA_ALLOW_UPGRADE_IN_CI=1` is set; blocked runs return `status: "manual"` with `ciBlocked: true` and suggest `agora upgrade --check --json`.
+- Align `go.mod` module path with the public repository: `github.com/AgoraIO/cli` (replaces the workspace-only `github.com/agora/cli-workspace/agora-cli-go` path).
+- Rename GitHub release archives from `agora-cli-go_v*` to `agora-cli_v*` starting in v0.2.1 (install scripts and docs use the new name). `agora upgrade` selects the archive prefix from the target release version: `agora-cli-go_*` for v0.1.7–v0.2.0, `agora-cli_*` for v0.2.1+.
+
+### Fixed
+
+- Disable git credential helpers for quickstart clone subprocesses so `agora init` and `agora quickstart create` succeed in non-interactive agent and CI environments without macOS keychain access.
+- Pass `--` before the repo URL and target directory on `git clone` so values starting with `-` cannot be parsed as git options.
+- Fail fast with `QUICKSTART_GIT_MISSING` when `git` is not on `PATH`, with `QUICKSTART_REF_INVALID` for malformed `--ref` values, and with `QUICKSTART_REPO_OVERRIDE_INVALID` when the env override URL is malformed, instead of surfacing cryptic git errors.
+
+### Upgrade notes
+
+**Direct installer (`install.sh` / `install.ps1`):** Fresh installs and re-runs of the installer fetch the correct archive name automatically. If you are on v0.1.7 through v0.2.0 and `agora upgrade` fails to download v0.2.1+, re-run the installer once:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
+```
+
+Those older binaries only know the `agora-cli-go_*` archive prefix; after one reinstall, future upgrades use `agora-cli_*`.
+
+**npm / package managers:** Use your package manager as usual (`npm update -g agoraio-cli`, etc.). Archive naming does not affect npm installs.
+
+**Automation scripts:**
+
+| Before | After |
+| ------ | ----- |
+| `agora init demo --yes` (silent template pick) | `agora init demo --template nextjs --yes` (required) |
+| `agora upgrade` in CI jobs | `agora upgrade --check --json` (non-mutating) |
+| `agora open --target docs` in CI | URL-only by default; pass `--browser` to force launch |
+
+Set `AGORA_ALLOW_UPGRADE_IN_CI=1` only when a CI job intentionally needs to mutate the installed binary.
+
+### Documentation
+
+- Align `AGENTS.md` with shipped `project doctor --deep` behavior and document current `agora open` browser-launch rules.
+- Expand `docs/automation.md` and `docs/llms.txt` with MCP transport/auth caveats, headless CI guidance, init/upgrade automation fields, and `agora env-help` discovery pointers.
+- Update agent quickstart rule and skills examples to include deterministic init (`--new-project`) defaults.
+- Document MCP progress notifications (`_meta.progressToken`) in `docs/automation.md`, `docs/llms.txt`, `agora mcp serve` help, and the skills catalog.
+- Document envelope versioning policy, login NDJSON parsing, raw `project env` hints, and boolean config flag syntax (`--flag=false`) in automation and troubleshooting docs.
+- Surface enterprise install paths for locked-down environments in `README.md` and `docs/install.md`.
+- Fix contributor clone path in `CONTRIBUTING.md` to match the canonical `git clone … && cd cli/` layout.
+- Align npm package `repository.directory` paths with the repo root layout and update the issue template docs link.
+- Document archive naming and upgrade migration in `docs/install.md` and `docs/troubleshooting.md`.
+- Add a GitHub Pages skip link for keyboard navigation.
+
 ## [0.2.0] - 2026-05-05
 
 ### Added
@@ -199,7 +260,8 @@ Earlier entries pre-date this convention and only carry their version's compare
 - 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.0...HEAD
+[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/AgoraIO/cli/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/AgoraIO/cli/compare/v0.1.9...v0.2.0
 [0.1.9]: https://github.com/AgoraIO/cli/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/AgoraIO/cli/compare/v0.1.7...v0.1.8
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 13eb7f8..c693a37 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -44,8 +44,7 @@ Requirements:
 
 ```bash
 git clone https://github.com/AgoraIO/cli.git
-cd cli/agora-cli-go
-
+cd cli/
 go build -trimpath -o agora .
 ./agora --help
 ```
diff --git a/README.md b/README.md
index aa8abac..d7be917 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,8 @@ npm install -g agoraio-cli
 irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 | iex
 ```
 
+Locked-down environments that block `curl | sh` can use npm, download a release archive from GitHub, or mirror the binary internally. Every release includes `checksums.txt`, a Cosign keyless signature, and an SBOM; see [docs/install.md](docs/install.md#enterprise--locked-down-environments) for manual tarball and verification steps.
+
 Notes:
 
 - The shell installer supports macOS, Linux, and Windows POSIX shells such as Git Bash. Use `install.ps1` for native PowerShell installs on Windows.
@@ -308,7 +310,7 @@ GitHub Actions are configured for:
 
 Release workflow behavior:
 
-- a pushed tag matching `v*` (for example `v0.2.0`) triggers the release workflow
+- a pushed tag matching `v*` (for example `v0.2.1`) triggers the release workflow
 - the workflow runs tests, builds release binaries, packages them, and publishes a GitHub release automatically
 - release artifacts include checksums
 
diff --git a/RELEASING.md b/RELEASING.md
index 43833a5..024798c 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -5,15 +5,15 @@ Releases are fully automated via GoReleaser. Pushing a `v*` tag is the only manu
 ## Release
 
 ```bash
-git tag v0.2.0
-git push origin v0.2.0
+git tag v0.2.1
+git push origin v0.2.1
 ```
 
 The release workflow (`.github/workflows/release.yml`) then:
 
 1. **GoReleaser** builds and publishes everything in parallel:
    - Cross-platform binaries (Linux, macOS, Windows — amd64 + arm64)
-   - Archives: `.tar.gz` (Unix), `.zip` (Windows)
+   - Archives: `agora-cli_v<version>_<os>_<arch>.{tar.gz,zip}` (v0.2.1+; older releases used `agora-cli-go_v*`)
    - Linux packages: `.deb`, `.rpm`, `.apk`
    - GitHub release with auto-generated changelog and checksums
    - Docker images → GitHub Container Registry (`ghcr.io/{owner}/agora-cli`)
@@ -33,6 +33,10 @@ The release workflow (`.github/workflows/release.yml`) then:
    - Rebuilds the signed apt repo on GitHub Pages
    - Requires `APT_SIGNING_KEY` secret + `APT_SIGNING_KEY_ID` variable
 
+## Release notes
+
+Before tagging, ensure [CHANGELOG.md](CHANGELOG.md) has the version section finalized, including any migration or upgrade notes. GoReleaser publishes auto-generated release notes from commits; paste highlights from the CHANGELOG section into the GitHub release description if you want a curated summary.
+
 ## Local Verification
 
 Before cutting a tag:
diff --git a/cmd/gendocs/main.go b/cmd/gendocs/main.go
index 26806e9..2b8437b 100644
--- a/cmd/gendocs/main.go
+++ b/cmd/gendocs/main.go
@@ -17,7 +17,7 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/agora/cli-workspace/agora-cli-go/internal/cli"
+	"github.com/AgoraIO/cli/internal/cli"
 )
 
 func main() {
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index 0eae2f5..b30a854 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -19,6 +19,7 @@
     <link rel="stylesheet" href="{{ '/assets/css/site.css' | relative_url }}">
   </head>
   <body>
+    <a class="skip-link" href="#main-content">Skip to content</a>
     <div class="page-shell">
       <header class="site-header" aria-label="Site header">
         <a class="brand" href="{{ '/' | relative_url }}" aria-label="Agora CLI Docs home">
diff --git a/docs/agents/README.md b/docs/agents/README.md
index 59dfbdc..733281c 100644
--- a/docs/agents/README.md
+++ b/docs/agents/README.md
@@ -9,9 +9,9 @@ These snippets help AI coding agents use Agora CLI safely and consistently in ap
 Use the CLI to scaffold rules into a new quickstart:
 
 ```bash
-agora init my-nextjs-demo --template nextjs --add-agent-rules cursor
-agora init my-python-demo --template python --add-agent-rules claude
-agora init my-go-demo --template go --add-agent-rules windsurf
+agora init my-nextjs-demo --template nextjs --new-project --add-agent-rules cursor
+agora init my-python-demo --template python --new-project --add-agent-rules claude
+agora init my-go-demo --template go --new-project --add-agent-rules windsurf
 ```
 
 Available rule targets:
diff --git a/docs/assets/css/site.css b/docs/assets/css/site.css
index 23877b0..e657ea2 100644
--- a/docs/assets/css/site.css
+++ b/docs/assets/css/site.css
@@ -77,6 +77,22 @@ a:focus-visible {
   outline-offset: 3px;
 }
 
+.skip-link {
+  position: absolute;
+  left: 1rem;
+  top: 0.75rem;
+  z-index: 10;
+  padding: 0.6rem 0.85rem;
+  border-radius: 9999px;
+  background: var(--panel);
+  box-shadow: var(--shadow);
+  transform: translateY(-150%);
+}
+
+.skip-link:focus {
+  transform: translateY(0);
+}
+
 .page-shell {
   width: 100%;
   max-width: 1200px;
diff --git a/docs/automation.md b/docs/automation.md
index d97393d..4488908 100644
--- a/docs/automation.md
+++ b/docs/automation.md
@@ -18,7 +18,9 @@ Use this guide for:
 - [Project Resolution Precedence](#project-resolution-precedence)
 - [Config Isolation](#config-isolation)
 - [JSON Envelope](#json-envelope)
+- [Envelope Versioning](#envelope-versioning)
 - [Progress Events (NDJSON Stream)](#progress-events-ndjson-stream)
+- [MCP Progress Notifications](#mcp-progress-notifications)
 - [Exit Codes](#exit-codes)
 - [Stable Result Shapes](#stable-result-shapes)
 - [Human vs Machine Output](#human-vs-machine-output)
@@ -39,10 +41,11 @@ Use this guide for:
 - Use `--debug` (equivalent to `AGORA_DEBUG=1`) to echo structured log records to stderr. The flag does not change exit codes, JSON envelope shape, or NDJSON progress events; it only mirrors the entries that would normally be written to the log file. Pair with `--json` for fully machine-parseable runs that also surface internal events to your CI logs. v0.2.0 dropped the legacy `--verbose` / `-v` alias and the `AGORA_VERBOSE` env var; persisted configs that contain a `verbose` key are auto-promoted to `debug` on first load.
 - Use `--yes` (or `-y`) / `AGORA_NO_INPUT=1` to assume the default answer to confirmation prompts. Following industry convention for `-y` (apt-style), the flag never starts brand-new interactive flows: in JSON, CI, or non-TTY contexts the CLI still fails fast with the same `AUTH_UNAUTHENTICATED` error you would have seen without `--yes`, instead of silently launching an OAuth browser flow.
 - Interactive login prompts only appear in interactive pretty-mode TTY runs. Automation should authenticate up front with `agora login`; `--json`, `AGORA_OUTPUT=json`, detected CI environments, and non-TTY stdin all skip the prompt and fail with `AUTH_UNAUTHENTICATED`.
+- In non-interactive runs (`--yes`, JSON, CI, non-TTY), pass `--template` explicitly to `agora init`. The CLI now fails fast with `QUICKSTART_TEMPLATE_REQUIRED` instead of silently selecting a template.
 - Output mode precedence is: explicit CLI flag (`--json` or `--output`) first, user-set `AGORA_OUTPUT` second, then user-customized config file value, then **CI auto-detect → JSON** (see below), then pretty.
 - Set `AGORA_AGENT=<tool-name>` in automated environments to explicitly label agent traffic in the API `User-Agent`. When unset, the CLI may infer a coarse label such as `cursor`, `claude-code`, `cline`, `windsurf`, `codex`, or `aider` from known agent environment markers. Set `AGORA_AGENT_DISABLE_INFER=1` to disable inference.
 - Use `agora mcp serve` to expose local Agora CLI tools to MCP-capable agents. The full surface is exposed: `agora.version`, `agora.introspect`, `agora.auth.{status,logout}`, `agora.config.{path,get}`, `agora.telemetry.status`, `agora.upgrade.check`, `agora.project.{list,show,use,create,doctor,env,env_write}`, `agora.project.feature.{list,status,enable}`, `agora.quickstart.{list,create,env_write}`, and `agora.init`. Authentication is intentionally **not** exposed via MCP because OAuth requires an interactive browser; run `agora login` once on the host first.
-- Use `agora open --target docs` for the human GitHub Pages docs and `agora open --target docs-md` for the agent-facing raw Markdown index. The Markdown tree is published under predictable `/md/` URLs, for example `/md/commands.md`, `/md/automation.md`, and `/md/error-codes.md`.
+- Use `agora open --target docs` for the human GitHub Pages docs and `agora open --target docs-md` for the agent-facing raw Markdown index. In CI/non-TTY runs the command defaults to URL-only output unless `--browser` is set. The Markdown tree is published under predictable `/md/` URLs, for example `/md/commands.md`, `/md/automation.md`, and `/md/error-codes.md`.
 - Docs publishing reads `docs/site.env` for `CLI_DOCS_BASE_URL` and `CLI_DOCS_MD_BASE_URL`; staging Pages builds can override those environment variables at workflow time without changing docs content. The resolved values are published as `/docs.env` for transparency.
 - The CLI maintains a short-lived on-disk completion cache for `agora project use <TAB>` under `<AGORA_HOME>/cache/projects.json`. The cache is only used for completions when a **local unexpired session exists** (`session.json` with a non-empty access token and a future `expiresAt`, when present), so Tab does not suggest stale project names after logout or local session expiry. The cache TTL is 5 minutes by default; override with `AGORA_PROJECT_CACHE_TTL_SECONDS=<seconds>` (set to `0` to disable). Cache files older than 24 h are pruned at every CLI startup. Set `AGORA_DISABLE_CACHE=1` to drop the cache on the next startup. The cache is invalidated automatically by `agora logout` and `agora project create` (the latter clears the file; it does not embed the new project until the next successful list fetch). To **force-refresh** the cached completion page, run `agora project list --refresh-cache` while authenticated; that command fetches the unfiltered first page used by completion and rewrites `projects.json` when it succeeds.
 
@@ -147,6 +150,12 @@ Wrappers that want compile-time type safety can generate types from the
 schema with `quicktype`, `datamodel-code-generator`, or any
 JSON-Schema-aware tool.
 
+## Envelope Versioning
+
+The current contract is `envelope.v1.json`. Minor CLI releases may add fields to envelopes, progress events, command result `data`, and introspection records. Agents must ignore unknown fields.
+
+Breaking envelope changes require a new schema file such as `envelope.v2.json`, a `CHANGELOG.md` entry, and a migration note in this document. Removing fields, changing field types, or changing the meaning of existing enum values is treated as breaking.
+
 ### One documented exception: `agora project env`
 
 `agora project env` is the only command whose **default** (non-JSON)
@@ -174,6 +183,8 @@ has the same shape as every other command. `agora project env write`
 already emits the unified envelope under all output modes — only the
 read path has the raw-stdout exception above.
 
+In interactive pretty TTY sessions, running `agora project env` without an explicit `--format`, `--shell`, or `--json` prints a stderr hint pointing agents to `--json` / `--format envelope`. The hint is not emitted in JSON mode or non-TTY automation.
+
 ## Progress Events (NDJSON Stream)
 
 Long-running commands emit one or more **progress events** to stdout ahead of the final envelope when `--json` is set. The wire format is **NDJSON** (newline-delimited JSON): one complete JSON object per line, terminated by `\n`.
@@ -200,6 +211,7 @@ Additional stage-specific fields may appear (for example `repoUrl`, `projectId`,
 
 | Stage | Emitted by | When | Stage-specific fields |
 |-------|------------|------|------------------------|
+| `clone:override` | `quickstart create`, `init` | Before `clone:start` when an `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL` override is in use | `repoUrl`, `envVar` |
 | `clone:start` | `quickstart create`, `init` | Before the `git clone` shell-out | `repoUrl`, `targetPath`, `ref` |
 | `clone:complete` | `quickstart create`, `init` | After `git clone` succeeds | `targetPath` |
 | `project:create` | `init` | Before creating a new Agora project | `projectName`, `features` |
@@ -229,19 +241,40 @@ Additional stage-specific fields may appear (for example `repoUrl`, `projectId`,
 
 Stages are stable identifiers; new stages may be added over time. Agents should treat unknown stages as benign progress information rather than failing on them.
 
-### MCP transport caveat: progress events collapse into the tool result
+## MCP Progress Notifications
 
-When the same long-running commands (`agora init`, `agora quickstart create`, `agora project create`, `agora login`) are invoked **through the MCP server** (`agora mcp serve`), the NDJSON progress event stream is **not** surfaced to the MCP client. MCP clients receive the final result payload only — JSON-stringified into the standard `content[0].text` slot of the `tools/call` response.
+When long-running tools are invoked through MCP with `_meta.progressToken`, `agora mcp serve` forwards stage updates as JSON-RPC `notifications/progress` frames before the final `tools/call` response. This keeps stdio framing valid while allowing host agents to display progress.
+
+Example `tools/call` params:
+
+```json
+{
+  "name": "agora.quickstart.create",
+  "arguments": {
+    "template": "nextjs",
+    "dir": "my-demo"
+  },
+  "_meta": {
+    "progressToken": "demo-1"
+  }
+}
+```
+
+Example progress notification:
+
+```json
+{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"demo-1","progress":1,"stage":"clone:start","message":"Cloning quickstart repository","timestamp":"..."}}
+```
 
-Why: MCP's stdio transport uses stdout for JSON-RPC framing, so any extra newline-delimited objects emitted before the final response would corrupt the transport. The progress events are still produced internally but are intentionally swallowed before they reach the client.
+The final MCP tool result is unchanged: the CLI result payload is JSON-stringified into `content[0].text`.
 
 Implications for agent authors:
 
-- Do not rely on `stage`-based hooks (e.g. progress UIs, mid-flight cancellation prompts) when calling these tools over MCP. Use them only when shelling out to `agora ... --json` directly.
+- Use `_meta.progressToken` when calling `agora.init`, `agora.quickstart.create`, or `agora.project.create` and your host can display progress notifications.
+- Without a progress token, MCP calls remain a single final response.
 - Plan for higher tail latency on MCP `tools/call` for the affected tools; the user-visible "nothing is happening" gap may be tens of seconds for git clones or project creation. Consider surfacing your own "running tool: agora.init…" UI in the host agent.
 - The terminal payload shape returned in `content[0].text` is identical to the CLI's terminal `data` envelope, so existing JSON-shape handlers continue to work unchanged.
-
-When future MCP transports support server-initiated `notifications/progress` (an open spec area), the CLI can add native MCP progress forwarding without changing the existing tool result shape.
+- Shell commands (`agora ... --json`) still use NDJSON progress events followed by the terminal envelope.
 
 Failure example:
 
@@ -278,6 +311,28 @@ Known `error.code` values are cataloged in [error-codes.md](error-codes.md).
 
 The following commands are part of the documented JSON contract.
 
+### `introspect`
+
+Example:
+
+```bash
+./agora introspect --json
+```
+
+Required `data` fields:
+- `commands`
+  Array of enumerable command metadata.
+- `globalFlags`
+  Root flags inherited by commands.
+- `pseudoCommands`
+  Stable command labels emitted by root flags such as `agora --upgrade-check`.
+- `enums`
+  Known enum values for agent validation.
+- `version`
+  Build metadata.
+
+Each `commands[]` item includes `path`, `command`, `short`, `flags`, `headlessSafe`, and `interactivity`. Agents should use `headlessSafe=false` to avoid flows that require direct user interaction, and use `interactivity` for a human-readable reason such as `interactive-browser`, `stdio-server`, or `browser-in-interactive-pretty-mode`.
+
 ### `init`
 
 Example:
@@ -288,6 +343,7 @@ Example:
 ```
 
 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`.
 
 Required `data` fields:
 - `action`
@@ -300,6 +356,8 @@ Required `data` fields:
   Boolean mirror for agents that branch on init reuse.
 - `projectId`
 - `projectName`
+- `projectSelectionReason`
+  One of `explicit_project`, `new_project`, `no_existing_projects`, `default_name`, `interactive_new_project`, `interactive_selection`, or `most_recent`.
 - `region`
 - `path`
   Absolute path to the cloned quickstart.
@@ -734,6 +792,8 @@ Example:
 ./agora auth login --json
 ```
 
+`login --json` is an NDJSON stream, not a single JSON blob: it emits `oauth:waiting`, `oauth:received`, and `oauth:complete` progress events before the final envelope. Parse stdout line-by-line and use the last object with top-level `ok` as the command result.
+
 Required `data` fields:
 - `action`
   Always `login`.
@@ -909,6 +969,8 @@ Example:
 ./agora config update --telemetry-enabled=false --json
 ```
 
+Boolean config flags use Cobra's explicit false syntax. To disable a boolean, pass `--flag=false` (for example `--telemetry-enabled=false`, `--browser-auto-open=false`, or `--debug=false`); omitting the flag leaves the persisted value unchanged.
+
 Returns the updated config object with the same shape as `config get`. Safe branch fields are the same as `config get`.
 
 ### `upgrade`
@@ -921,6 +983,8 @@ Example:
 ./agora --upgrade-check --json
 ```
 
+CI/agent guidance: prefer `--check` (or `--upgrade-check`) so automation does not mutate the running binary.
+
 Required `data` fields:
 - `action`
   `upgrade` for the subcommand and `upgrade-check` for the root `--upgrade-check` pseudo-command.
@@ -948,9 +1012,15 @@ Optional fields:
   Structured version payload for `agora --upgrade-check`.
 - `receiptWarning`
   Nonfatal warning when a direct-installer self-update succeeded but the CLI could not refresh `agora.install.json`.
+- `ciBlocked`
+  Present and `true` when installer-managed self-update is skipped because CI auto-detect is active and `AGORA_ALLOW_UPGRADE_IN_CI` is not set.
+- `suggestedCommand`
+  Suggested non-mutating check command when `ciBlocked` is true.
 
 Upgrade behavior:
 - direct-installer installs (`installMethod: "installer"`) self-update in place after downloading the GitHub release archive and verifying it against `checksums.txt`
+- archive prefix is version-aware: `agora-cli-go_*` for target releases v0.1.7–v0.2.0, `agora-cli_*` for v0.2.1+
+- in CI, installer-managed self-update is skipped by default (`status: "manual"` + `ciBlocked: true`); set `AGORA_ALLOW_UPGRADE_IN_CI=1` to opt in
 - package-manager installs return `status: "manual"` with the owning package-manager command; agents should run that command only after user approval
 - `unknown` means the CLI could not verify the install channel, usually because the binary is a development/test build
 
diff --git a/docs/commands.md b/docs/commands.md
index 06545c6..43c4195 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -158,7 +158,8 @@ Open Agora Console or CLI docs
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
-| `--no-browser` | `bool` | — | print the URL without opening a browser |
+| `--browser` | `bool` | — | force opening a browser even in CI/non-TTY pretty sessions |
+| `--no-browser` | `bool` | — | always print the URL without opening a browser |
 | `--target` | `string` | `console` | target to open: console, docs, docs-md, or product-docs |
 
 ### `agora project`
diff --git a/docs/devex-backlog.md b/docs/devex-backlog.md
deleted file mode 100644
index 2150cac..0000000
--- a/docs/devex-backlog.md
+++ /dev/null
@@ -1,157 +0,0 @@
----
-title: DevEx backlog (prioritized)
----
-
-# Developer experience backlog
-
-Prioritized follow-ups from the DevEx review (human + agentic developers).  
-Update this file as items ship or priorities change.
-
-## Legend
-
-| Priority | Meaning |
-| -------- | ------- |
-| **P0** | Blocks adoption or trust (wrong paths, misleading guarantees, security perception). |
-| **P1** | High-impact polish for clarity, consistency, or agent reliability. |
-| **P2** | Strategic improvements, coordination outside this repo, or deeper test coverage. |
-
----
-
-## P0
-
-### P0-1 — Contributor clone path matches canonical repo layout
-
-**Problem:** `CONTRIBUTING.md` instructs `cd cli/agora-cli-go` after cloning `AgoraIO/cli`. If the default clone layout differs (single-package repo vs monorepo), new contributors hit a broken path immediately.
-
-**Target files**
-
-- [`CONTRIBUTING.md`](../CONTRIBUTING.md)
-- Optionally [`README.md`](../README.md) “Build from source” if it duplicates the path
-
-**Acceptance criteria**
-
-- [ ] Paths match the **actual** default layout of `github.com/AgoraIO/cli` (verify on default branch).
-- [ ] If multiple layouts exist (e.g. subtree mirror), document **both** with a one-line “use this if…” disambiguation.
-- [ ] `make test` / `go build` instructions run verbatim from a fresh clone.
-
----
-
-### P0-2 — Enterprise-friendly install entry point
-
-**Problem:** Teams that block `curl | sh` need a obvious first-class path (npm, package managers, manual tarball + verify) without digging through long install docs.
-
-**Target files**
-
-- [`README.md`](../README.md) — short **Enterprise / locked-down environments** subsection near Install.
-- [`docs/install.md`](install.md) — optional anchor target if README stays minimal.
-
-**Acceptance criteria**
-
-- [ ] README surfaces **non–pipe-to-shell** options in under ~15 lines (links out to `docs/install.md` for detail).
-- [ ] Mentions checksum / Cosign verification pointers (link to existing README or install sections).
-- [ ] No new promises beyond what installers actually support today.
-
----
-
-## P1
-
-### P1-1 — Align user-facing copy with `project doctor --deep` stability
-
-**Problem:** `AGENTS.md` notes `--deep` is not fully stable yet. User-facing docs must not imply guarantees agents/contributors do not have.
-
-**Target files**
-
-- [`README.md`](../README.md), [`docs/commands.md`](commands.md) (generated), [`docs/troubleshooting.md`](troubleshooting.md)
-- [`internal/cli/`](../internal/cli/) — Cobra `Long:` / `Example:` for `project doctor` if needed
-
-**Acceptance criteria**
-
-- [ ] Public docs describe `--deep` **exactly** as implemented (or omit until stable).
-- [ ] `go run ./cmd/gendocs` / `make docs-commands` refreshed if command text changes.
-
----
-
-### P1-2 — Agent discovery: MCP prerequisites + tool surface in one place
-
-**Problem:** Agents that fetch `llms.txt` but do not run the binary first still need a compact map of MCP tools and auth prerequisites (`agora login` on host).
-
-**Target files**
-
-- [`docs/llms.txt`](llms.txt)
-- [`docs/automation.md`](automation.md) — short subsection if you want normative detail beyond llms.txt
-
-**Acceptance criteria**
-
-- [ ] `llms.txt` links or summarizes: MCP auth model (login on host), transport (`stdio`), and pointer to [`docs/automation.md`](automation.md) for JSON/MCP alignment.
-- [ ] Tool list stays maintainable (either generated snippet from code or explicit list with “refresh when MCP surface changes” note in [`AGENTS.md`](../AGENTS.md)).
-
----
-
-### P1-3 — JSON schema / envelope versioning policy
-
-**Problem:** [`docs/schema/envelope.v1.json`](schema/envelope.v1.json) implies future versions; agents need a single place for deprecation and additive-only vs breaking rules.
-
-**Target files**
-
-- [`docs/automation.md`](automation.md)
-- [`CHANGELOG.md`](../CHANGELOG.md) — for any breaking envelope changes
-
-**Acceptance criteria**
-
-- [ ] Document how `envelope.vN.json` relates to releases (e.g. additive fields OK in minor; breaking only major).
-- [ ] Document where breaking changes are announced (changelog + automation.md “Migration” subsection).
-
----
-
-## P2
-
-### P2-1 — Contract tests for automation examples
-
-**Problem:** Golden tests cover slices of introspect; broader drift between `docs/automation.md` examples and actual CLI output can still slip through.
-
-**Target files**
-
-- [`internal/cli/integration_*_test.go`](../internal/cli/), [`internal/cli/golden_test.go`](../internal/cli/golden_test.go)
-- [`docs/automation.md`](automation.md)
-
-**Acceptance criteria**
-
-- [ ] Representative commands from automation.md are exercised in CI (or key paths extracted to shared test fixtures).
-- [ ] Failure messages point authors to `docs/automation.md` / `make docs-commands` / error-code script as appropriate.
-
----
-
-### P2-2 — Cross-link from Agora product / Console developer surfaces
-
-**Problem:** Developers and agents often land on product docs first; discovery of CLI mirror URLs is faster with inbound links.
-
-**Target:** Agora properties **outside** this repository (Console, developer portal, RTC docs). Track as a DevRel coordination task.
-
-**Acceptance criteria**
-
-- [ ] At least one canonical product doc page links to `https://agoraio.github.io/cli/` and `https://agoraio.github.io/cli/md/`.
-- [ ] Optional: link `https://agoraio.github.io/cli/llms.txt` for agent retrieval.
-
----
-
-### P2-3 — GitHub Pages accessibility pass
-
-**Problem:** Custom theme is good for branding; WCAG contrast and keyboard nav should be validated.
-
-**Target files**
-
-- [`docs/_layouts/default.html`](_layouts/default.html), [`docs/assets/css/site.css`](assets/css/site.css)
-
-**Acceptance criteria**
-
-- [ ] Spot-check focus states, heading order, and contrast on home + one inner page (light/dark).
-- [ ] Fix any **obvious** issues (missing button labels already partially addressed on index copy button — extend as needed).
-
----
-
-## Changelog
-
-| Date | Change |
-| ---- | ------ |
-| 2026-05-01 | Initial backlog from DevEx review. |
-| 2026-05-05 | v0.2.0 release date in `CHANGELOG.md` set to Tuesday 2026-05-05. |
diff --git a/docs/error-codes.md b/docs/error-codes.md
index 77b602b..9d2ffef 100644
--- a/docs/error-codes.md
+++ b/docs/error-codes.md
@@ -39,6 +39,9 @@ This catalog is the source of truth for stable codes. CI runs `make snapshot-err
 | `QUICKSTART_TEMPLATE_UNAVAILABLE` | 1 | The template exists but is not currently available. | Choose an available template. |
 | `QUICKSTART_TEMPLATE_ENV_UNSUPPORTED` | 1 | The selected template does not define an env target path. | Choose a template with env support or configure the env file manually. |
 | `QUICKSTART_TARGET_EXISTS` | 1 | The clone target already exists. | Choose a new directory. |
+| `QUICKSTART_REF_INVALID` | 1 | `--ref` is empty after trimming, starts with `-`, or contains whitespace/control characters. | Pass a valid git branch, tag, or commit (no leading `-`). |
+| `QUICKSTART_REPO_OVERRIDE_INVALID` | 1 | The `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL` env override is set to a malformed value. | Set the variable to an `https://`, `ssh://`, `git://`, `file://`, `git@host:path`, or absolute local path URL — or unset it. |
+| `QUICKSTART_GIT_MISSING` | 1 | `git` is required but was not found on `PATH`. | Install git (https://git-scm.com/downloads) and retry. |
 | `INIT_NAME_REQUIRED` | 1 | `agora init` was run without the required target directory name. | Pass a directory name, for example `agora init my-nextjs-demo --template nextjs`. |
 | `INIT_ABORTED` | 1 | The interactive `agora init` reuse prompt was answered "no". | Re-run with `--project <id>`, `--new-project`, or accept the prompt. |
 | `PROJECT_NAME_REQUIRED` | 1 | `agora project create` (or the equivalent MCP tool) was called without `name`. | Pass a project name, for example `agora project create my-app`. |
diff --git a/docs/install.md b/docs/install.md
index 3b07a01..197b3b3 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -6,6 +6,22 @@ title: Install Agora CLI
 
 This page lists the supported installation paths for Agora CLI and the direct installers for macOS, Linux, and Windows.
 
+## Enterprise / locked-down environments
+
+If your organization blocks pipe-to-shell installers, use one of these supported paths:
+
+```bash
+# npm package with provenance metadata
+npm install -g agoraio-cli
+
+# Manual release archive download
+curl -fsSLO https://github.com/AgoraIO/cli/releases/download/vX.Y.Z/agora-cli_vX.Y.Z_linux_amd64.tar.gz
+curl -fsSLO https://github.com/AgoraIO/cli/releases/download/vX.Y.Z/checksums.txt
+sha256sum -c checksums.txt --ignore-missing
+```
+
+Manual installs should verify SHA-256 at minimum; Cosign and SBOM verification are documented in [Security](#security). Enterprises may mirror the verified archive internally as long as the binary name remains `agora` / `agora.exe` on `PATH`.
+
 ## Direct Installers
 
 ### macOS, Linux, and Windows POSIX shells
@@ -22,7 +38,7 @@ agora --help
 Install a pinned version:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --version 0.2.0
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --version 0.2.1
 agora --help
 ```
 
@@ -64,7 +80,7 @@ agora --help
 Install a pinned version:
 
 ```powershell
-$env:VERSION = "0.2.0"
+$env:VERSION = "0.2.1"
 irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 | iex
 agora --help
 ```
@@ -144,7 +160,7 @@ Uninstall removes the binary and `agora.install.json` receipt from the install d
 Both direct installers support these core overrides:
 
 - `GITHUB_REPO`: install from a fork or alternate repository.
-- `VERSION`: install a specific version. Both `0.2.0` and `v0.2.0` are accepted.
+- `VERSION`: install a specific version. Both `0.2.1` and `v0.2.1` are accepted.
 - `INSTALL_DIR`: install to a custom directory.
 - `GITHUB_TOKEN` or `GH_TOKEN`: optional GitHub token to avoid API rate limits when resolving the latest release.
 
@@ -206,6 +222,17 @@ Direct installer runs (`install.sh` and `install.ps1`) write `agora.install.json
 
 Direct-installer installs self-update in place. Package-manager installs print the package-manager command and exit successfully so the package manager remains the owner of the installed files.
 
+### Release archive naming
+
+GitHub release archives follow this pattern:
+
+| Release version | Archive prefix | Example |
+| --------------- | -------------- | ------- |
+| v0.1.7 – v0.2.0 | `agora-cli-go_v*` | `agora-cli-go_v0.2.0_linux_amd64.tar.gz` |
+| v0.2.1 and later | `agora-cli_v*` | `agora-cli_v0.2.1_linux_amd64.tar.gz` |
+
+`install.sh`, `install.ps1`, and `agora upgrade` (v0.2.1+) select the correct prefix from the target release version. Binaries installed from v0.1.7–v0.2.0 that fail to self-update across the rename should re-run the installer once — see [troubleshooting.md](troubleshooting.md#upgrade-from-v017v020-fails).
+
 ## Build From Source
 
 Requirements:
@@ -243,7 +270,7 @@ agora --help
 npx agoraio-cli --help
 
 # Pin a specific version
-npm install -g agoraio-cli@0.2.0
+npm install -g agoraio-cli@0.2.1
 
 # Update to the latest published version
 npm update -g agoraio-cli
@@ -271,12 +298,12 @@ For one-off shell sessions, source the generated script according to your shell'
 If latest-version resolution fails, retry with a pinned version or provide `GITHUB_TOKEN` / `GH_TOKEN`:
 
 ```bash
-GITHUB_TOKEN=your-token-here VERSION=0.2.0 sh install.sh
+GITHUB_TOKEN=your-token-here VERSION=0.2.1 sh install.sh
 ```
 
 ```powershell
 $env:GITHUB_TOKEN = "your-token-here"
-$env:VERSION = "0.2.0"
+$env:VERSION = "0.2.1"
 & ([scriptblock]::Create((irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1)))
 ```
 
@@ -322,7 +349,7 @@ For CI, automation, and reproducible environments, pin `VERSION` explicitly inst
 Every release is signed with [Cosign](https://docs.sigstore.dev/cosign/overview/) using GitHub Actions OIDC (keyless mode) and ships an [SPDX 2.3](https://spdx.dev/) SBOM per archive and per Linux package. To verify the `checksums.txt` file before trusting any artifact:
 
 ```bash
-TAG=v0.2.0
+TAG=v0.2.1
 ASSET_BASE="https://github.com/AgoraIO/cli/releases/download/${TAG}"
 curl -fsSLO "${ASSET_BASE}/checksums.txt"
 curl -fsSLO "${ASSET_BASE}/checksums.txt.sig"
@@ -346,8 +373,8 @@ cosign verify "ghcr.io/agoraio/agora-cli:${TAG#v}" \
   --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'
 ```
 
-To audit dependencies, download the `*.spdx.json` SBOM that ships next to each archive (e.g. `agora-cli-go_v0.2.0_linux_amd64.tar.gz.spdx.json`) and feed it to a scanner such as [Grype](https://github.com/anchore/grype):
+To audit dependencies, download the `*.spdx.json` SBOM that ships next to each archive (e.g. `agora-cli_v0.2.1_linux_amd64.tar.gz.spdx.json`) and feed it to a scanner such as [Grype](https://github.com/anchore/grype):
 
 ```bash
-grype sbom:agora-cli-go_v0.2.0_linux_amd64.tar.gz.spdx.json
+grype sbom:agora-cli_v0.2.1_linux_amd64.tar.gz.spdx.json
 ```
diff --git a/docs/llms.txt b/docs/llms.txt
index 86b5871..d875887 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -7,7 +7,7 @@
 Install: curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
 
 Login: agora login
-Initialize project: agora init my-demo --template nextjs
+Initialize project: agora init my-demo --template nextjs --new-project
 Check project health: agora project doctor --json
 
 ## Documentation Index
@@ -44,6 +44,25 @@ Check project health: agora project doctor --json
 - **Agentic discovery**: `agora introspect --json` and `agora --help --all --json` emit the same machine-readable command tree
 - **MCP server**: `agora mcp serve` exposes the CLI as Model Context Protocol tools for agents
 
+## Agent and MCP Notes
+
+- **MCP transport**: `agora mcp serve` uses stdio JSON-RPC.
+- **Auth prerequisite**: `agora.auth.login` is intentionally not exposed over MCP. Run `agora login` on the host first.
+- **Progress over MCP**: Long-running tools emit `notifications/progress` when the MCP `tools/call` params include `_meta.progressToken`.
+- **When shelling out**: run commands like `agora init ... --json` and parse stdout line-by-line (progress events + final envelope).
+- **Capability discovery**: prefer `agora --help --all --json` or `agora introspect --json`.
+- **Environment catalog**: use `agora env-help --json` to enumerate all supported `AGORA_*` controls.
+
+## Headless / CI guidance
+
+- Use `--json` for automation and parse the terminal envelope.
+- Use explicit `--project <id|name>` or `--new-project` for deterministic init/project mutations.
+- Pass `--template` with `agora init --yes` in non-interactive runs (v0.2.1+).
+- `--yes` accepts confirmation defaults; it does not replace `agora login`.
+- Isolate per-job state with `AGORA_HOME="$(mktemp -d)"`.
+- For URL-only docs access in agents, use `agora open --target docs-md --json` (add `--browser` to force launch).
+- Prefer `agora upgrade --check --json` in CI; set `AGORA_ALLOW_UPGRADE_IN_CI=1` only when mutating the binary is intentional.
+
 ## Common Use Cases
 
 ### Login and Authentication
@@ -57,8 +76,8 @@ agora auth status --json
 ### Project Initialization
 ```
 agora init my-app --template nextjs
-agora init my-app --template python --yes
-agora init my-app --template go --json
+agora init my-app --template python --new-project --json
+agora init my-app --template go --project <project-id> --json
 ```
 
 ### Project Health Check
@@ -89,6 +108,7 @@ All commands except `agora project env` (raw stdout in dotenv/shell mode for `ev
 ```
 
 To get the JSON envelope for `project env`, pass `--json` (the raw dotenv/shell formats remain available via `--format dotenv` / `--format shell` for shell sourcing).
+Never parse the default raw `project env` output in agents; use `--json` or `--format envelope`.
 
 Exit codes (stable contract):
 - 0   success
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index e5566ca..4d332f6 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -67,15 +67,32 @@ older binary.
 
 ## `agora init` or `agora quickstart create` fails on `git clone`
 
-The CLI shells out to `git clone` for quickstarts. Verify:
+The CLI shells out to `git clone` for quickstarts. Most failures map to a stable error code:
+
+| Error code | Meaning | Fix |
+|------------|---------|-----|
+| `QUICKSTART_GIT_MISSING` | `git` is not on `PATH`. | Install git ([git-scm.com/downloads](https://git-scm.com/downloads)) and retry. |
+| `QUICKSTART_REF_INVALID` | `--ref` is empty, dash-prefixed, or contains whitespace. | Pass a valid branch/tag/commit. |
+| `QUICKSTART_REPO_OVERRIDE_INVALID` | The `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL` env override is malformed. | Set it to an `https://`, `ssh://`, `git://`, `file://`, `git@host:path`, or absolute local path URL — or unset it. |
+
+If the clone reaches git but still fails, verify connectivity:
 
 ```bash
 git --version
-git ls-remote https://github.com/AgoraIO/agora-quickstart-nextjs.git
+git ls-remote https://github.com/AgoraIO-Conversational-AI/agent-quickstart-nextjs.git
 ```
 
-If `git` is missing, install it (Homebrew, apt, winget, etc.). If
-network access fails, check proxies and corporate firewall rules.
+Check proxies and corporate firewall rules if `ls-remote` hangs or fails.
+
+The CLI invokes git with `-c credential.helper=` so credential helpers (including macOS keychain) are not consulted for these public clones — agent and CI subprocesses no longer fail with "Device not configured."
+
+Workshops and internal forks can override the clone URL per template, e.g.:
+
+```bash
+AGORA_QUICKSTART_NEXTJS_REPO_URL=https://github.com/my-org/fork agora init demo --template nextjs
+```
+
+A `clone:override` progress event is emitted whenever this is in use, so JSON automation runs show which fork was cloned.
 
 ## "project does not have an app certificate"
 
@@ -114,6 +131,48 @@ agora login
 Or set `AGORA_HOME=$(mktemp -d)` per job for an isolated session and
 provision credentials via your secret store before invoking the CLI.
 
+## CI accidentally self-upgraded the binary
+
+`agora upgrade` performs an in-place update for installer-managed installs.
+In CI and agent automation, prefer non-mutating checks:
+
+```bash
+agora upgrade --check --json
+agora --upgrade-check --json
+```
+
+Installer-managed self-update is blocked in CI by default (v0.2.1+). Blocked
+runs return `status: "manual"` with `ciBlocked: true` in JSON. Set
+`AGORA_ALLOW_UPGRADE_IN_CI=1` only when a job intentionally needs to mutate
+the installed binary.
+
+For package-manager installs, use the package manager's own upgrade command.
+
+## Upgrade from v0.1.7–v0.2.0 fails
+
+Release archives were renamed from `agora-cli-go_v*` to `agora-cli_v*`
+starting in v0.2.1. Binaries installed from v0.1.7 through v0.2.0 embed
+upgrade logic that only knows the old prefix, so `agora upgrade` may fail
+when downloading v0.2.1+.
+
+Re-run the installer once (it always fetches the latest script and archive
+names):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
+```
+
+npm and other package-manager installs are unaffected.
+
+## `agora init --yes` fails with QUICKSTART_TEMPLATE_REQUIRED
+
+In JSON, CI, or non-TTY runs, `agora init` requires an explicit template.
+Pass `--template` (list options with `agora quickstart list`):
+
+```bash
+agora init my-demo --template nextjs --new-project --yes --json
+```
+
 ## Output looks wrong in scripts (color codes, table widths)
 
 The CLI auto-detects CI and disables color and progress bars there. In
@@ -176,6 +235,18 @@ DO_NOT_TRACK=1 agora <command>
 
 See [Telemetry](telemetry.html) for the field schema.
 
+## Boolean config flags are not turning off
+
+Boolean flags in `agora config update` need explicit `=false` syntax. For example:
+
+```bash
+agora config update --telemetry-enabled=false
+agora config update --browser-auto-open=false
+agora config update --debug=false
+```
+
+Passing only `--telemetry-enabled` sets the value to true; omitting the flag leaves the existing config unchanged.
+
 ## Still stuck?
 
 - Open a [GitHub Discussion](https://github.com/AgoraIO/cli/discussions)
diff --git a/go.mod b/go.mod
index c300eda..f5b3b76 100644
--- a/go.mod
+++ b/go.mod
@@ -1,4 +1,4 @@
-module github.com/agora/cli-workspace/agora-cli-go
+module github.com/AgoraIO/cli
 
 go 1.26.3
 
diff --git a/install.ps1 b/install.ps1
index c686fc3..a8f2031 100644
--- a/install.ps1
+++ b/install.ps1
@@ -446,7 +446,7 @@ $tempRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("agora-install-" + [Sys
 
 try {
     Resolve-Version
-    $fileName = "agora-cli-go_v$Version" + "_windows_${arch}.zip"
+    $fileName = "agora-cli_v$Version" + "_windows_${arch}.zip"
     $archivePath = Join-Path $tempRoot $fileName
     $checksumsPath = Join-Path $tempRoot 'checksums.txt'
     $extractDir = Join-Path $tempRoot 'extract'
diff --git a/install.sh b/install.sh
index da65cf9..7a9aca2 100755
--- a/install.sh
+++ b/install.sh
@@ -1187,7 +1187,7 @@ main() {
     die "VERSION cannot be empty." "$EXIT_USAGE"
   fi
 
-  FILENAME="agora-cli-go_v${VERSION}_${OS}_${ARCH}.${ARCHIVE_EXT}"
+  FILENAME="agora-cli_v${VERSION}_${OS}_${ARCH}.${ARCHIVE_EXT}"
   ARCHIVE_URL="${RELEASES_DOWNLOAD_BASE_URL%/}/v${VERSION}/${FILENAME}"
   CHECKSUMS_URL="${RELEASES_DOWNLOAD_BASE_URL%/}/v${VERSION}/checksums.txt"
   ARCHIVE_PATH="${TMP}/${FILENAME}"
diff --git a/internal/cli/commands.go b/internal/cli/commands.go
index db1faeb..191cd03 100644
--- a/internal/cli/commands.go
+++ b/internal/cli/commands.go
@@ -264,7 +264,10 @@ When the binary was installed with install.sh / install.ps1, this command perfor
 
 For Homebrew, npm, and other package-manager-managed installs, the command prints the recommended upgrade command and exits successfully (status: "manual"). It will not shadow a managed install.
 
-Use --check to resolve the latest version and report what would happen without writing anything.`,
+Use --check to resolve the latest version and report what would happen without writing anything.
+
+In CI and agent automation, prefer --check (or the root --upgrade-check flag)
+so runs stay deterministic and do not mutate the binary under test.`,
 		Example: example(`
   agora upgrade
   agora upgrade --check --json
@@ -286,6 +289,7 @@ Use --check to resolve the latest version and report what would happen without w
 func (a *App) buildOpenCommand() *cobra.Command {
 	var target string
 	var noBrowser bool
+	var browser bool
 	cmd := &cobra.Command{
 		Use:   "open",
 		Short: "Open Agora Console or CLI docs",
@@ -294,21 +298,31 @@ func (a *App) buildOpenCommand() *cobra.Command {
   agora open --target docs
   agora open --target docs-md
   agora open --target product-docs
+  agora open --target docs --browser
 `),
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			url, err := resolveOpenTarget(target, a.osEnv)
 			if err != nil {
 				return err
 			}
+			if browser && noBrowser {
+				return &cliError{Message: "choose only one of --browser or --no-browser"}
+			}
 			status := "printed"
-			if !noBrowser && a.resolveOutputMode(cmd) != outputJSON && openBrowser(url) {
+			mayAutoOpen := !noBrowser &&
+				!isCIEnvironment(a.osEnv) &&
+				isTTY(os.Stderr) &&
+				a.resolveOutputMode(cmd) != outputJSON
+			shouldOpen := browser || mayAutoOpen
+			if shouldOpen && openBrowser(url) {
 				status = "opened"
 			}
 			return renderResult(cmd, "open", map[string]any{"action": "open", "status": status, "target": target, "url": url})
 		},
 	}
 	cmd.Flags().StringVar(&target, "target", "console", "target to open: console, docs, docs-md, or product-docs")
-	cmd.Flags().BoolVar(&noBrowser, "no-browser", false, "print the URL without opening a browser")
+	cmd.Flags().BoolVar(&noBrowser, "no-browser", false, "always print the URL without opening a browser")
+	cmd.Flags().BoolVar(&browser, "browser", false, "force opening a browser even in CI/non-TTY pretty sessions")
 	return cmd
 }
 
@@ -778,6 +792,9 @@ For automation, prefer --json (or --format envelope) so the result has the same
 				})
 			}
 			_, err = fmt.Fprint(cmd.OutOrStdout(), renderProjectEnv(values, format))
+			if err == nil && format != envJSON && !cmd.Flags().Changed("format") && !cmd.Flags().Changed("shell") && a.resolveOutputMode(cmd) == outputPretty && isTTY(os.Stderr) {
+				fmt.Fprintln(cmd.ErrOrStderr(), "Tip: `agora project env` prints raw dotenv by default. Use `--json` or `--format envelope` for automation.")
+			}
 			return err
 		},
 	}
diff --git a/internal/cli/env_help.go b/internal/cli/env_help.go
index 8640b76..723bb89 100644
--- a/internal/cli/env_help.go
+++ b/internal/cli/env_help.go
@@ -34,6 +34,7 @@ func agoraEnvCatalog() []agoraEnvVar {
 		{Name: "AGORA_NO_INPUT", Category: "interaction", Description: "When set, accept default for confirmation prompts (alias of --yes). Never starts a new interactive OAuth flow in JSON/CI/non-TTY contexts.", Default: "0", Effect: "0 | 1 | true | yes | y"},
 		{Name: "AGORA_BROWSER_AUTO_OPEN", Category: "interaction", Description: "When 0, never auto-open a browser for OAuth login (forces --no-browser semantics).", Default: "1", Effect: "0 | 1"},
 		{Name: "AGORA_LOGIN_TIMEOUT_MS", Category: "interaction", Description: "How long to wait for the OAuth callback before giving up.", Default: "300000", Effect: "milliseconds"},
+		{Name: "AGORA_ALLOW_UPGRADE_IN_CI", Category: "interaction", Description: "When 1, allow installer-managed `agora upgrade` to mutate the binary in CI environments.", Default: "0", Effect: "0 | 1 | true | yes | y"},
 		// Storage / paths
 		{Name: "AGORA_HOME", Category: "storage", Description: "Override the directory the CLI uses for config, session, context, cache, and logs.", Effect: "absolute path"},
 		{Name: "AGORA_DISABLE_CACHE", Category: "storage", Description: "When 1, disable the on-disk project list cache used for shell completion.", Default: "0", Effect: "0 | 1"},
@@ -46,6 +47,7 @@ func agoraEnvCatalog() []agoraEnvVar {
 		{Name: "AGORA_CONSOLE_URL", Category: "endpoints", Description: "Override the URL used by `agora open --target console`."},
 		{Name: "AGORA_DOCS_URL", Category: "endpoints", Description: "Override the URL used by `agora open --target docs`."},
 		{Name: "AGORA_PRODUCT_DOCS_URL", Category: "endpoints", Description: "Override the URL used by `agora open --target product-docs`."},
+		{Name: "AGORA_QUICKSTART_<TEMPLATE>_REPO_URL", Category: "endpoints", Description: "Override the clone URL for a specific quickstart template (e.g. AGORA_QUICKSTART_NEXTJS_REPO_URL). Used for workshops, internal forks, and integration tests; everyday users do not set this.", Effect: "https:// | ssh:// | git:// | file:// | git@host:path | absolute local path"},
 		// Telemetry
 		{Name: "DO_NOT_TRACK", Category: "telemetry", Description: "Standard DO_NOT_TRACK convention; hard opt-out of telemetry and file logging.", Effect: "any non-empty value"},
 		{Name: "AGORA_SENTRY_ENABLED", Category: "telemetry", Description: "When 0, disable telemetry transport even if config has telemetryEnabled=true.", Default: "1", Effect: "0 | 1"},
diff --git a/internal/cli/init.go b/internal/cli/init.go
index f637e44..73fc7ee 100644
--- a/internal/cli/init.go
+++ b/internal/cli/init.go
@@ -117,12 +117,7 @@ Use --feature to specify which features to enable on a newly created project (re
 
 func (a *App) selectInitTemplate(cmd *cobra.Command) (string, error) {
 	if a.noInput() {
-		for _, template := range quickstartTemplates() {
-			if template.Available && template.SupportsInit {
-				return template.ID, nil
-			}
-		}
-		return "", &cliError{Message: "no init-compatible quickstart templates are available.", Code: "QUICKSTART_TEMPLATE_UNAVAILABLE"}
+		return "", &cliError{Message: "quickstart template is required. Pass `--template` or run `agora quickstart list`.", Code: "QUICKSTART_TEMPLATE_REQUIRED"}
 	}
 	if a.resolveOutputMode(cmd) == outputJSON || isCIEnvironment(a.osEnv) || !isTTY(os.Stdin) {
 		return "", &cliError{Message: "quickstart template is required. Pass `--template` or run `agora quickstart list`.", Code: "QUICKSTART_TEMPLATE_REQUIRED"}
@@ -347,6 +342,7 @@ func (a *App) resolveInitProject(ctx projectContext, item projectSummary) (proje
 func (a *App) initProject(name, targetDir string, template quickstartTemplate, existingProject, region string, features []string, rtmDataCenter string, newProject bool, promptForReuse bool, promptOut io.Writer, promptIn io.Reader, progress progressEmitter) (map[string]any, error) {
 	var target projectTarget
 	projectAction := "existing"
+	projectSelectionReason := "explicit_project"
 	enabledFeatures := []string{}
 	needsCreate := false
 	createdRTMDataCenter := ""
@@ -360,6 +356,7 @@ func (a *App) initProject(name, targetDir string, template quickstartTemplate, e
 		target = resolved
 	case newProject:
 		needsCreate = true
+		projectSelectionReason = "new_project"
 	default:
 		ctx, items, err := a.listInitProjects()
 		if err != nil {
@@ -367,6 +364,7 @@ func (a *App) initProject(name, targetDir string, template quickstartTemplate, e
 		}
 		if len(items) == 0 {
 			needsCreate = true
+			projectSelectionReason = "no_existing_projects"
 			break
 		}
 		if item, ok := selectDefaultInitProjectFromList(items); ok {
@@ -375,6 +373,7 @@ func (a *App) initProject(name, targetDir string, template quickstartTemplate, e
 				return nil, err
 			}
 			target = resolved
+			projectSelectionReason = "default_name"
 			break
 		}
 		if promptForReuse {
@@ -387,17 +386,20 @@ func (a *App) initProject(name, targetDir string, template quickstartTemplate, e
 				return nil, &cliError{Message: "init aborted by user.", Code: "INIT_ABORTED"}
 			case "new":
 				needsCreate = true
+				projectSelectionReason = "interactive_new_project"
 			default:
 				resolved, err := a.resolveInitProject(ctx, selected)
 				if err != nil {
 					return nil, err
 				}
 				target = resolved
+				projectSelectionReason = "interactive_selection"
 			}
 		} else {
 			item, ok := selectInitProjectFromList(items)
 			if !ok {
 				needsCreate = true
+				projectSelectionReason = "no_existing_projects"
 				break
 			}
 			resolved, err := a.resolveInitProject(ctx, item)
@@ -405,6 +407,7 @@ func (a *App) initProject(name, targetDir string, template quickstartTemplate, e
 				return nil, err
 			}
 			target = resolved
+			projectSelectionReason = "most_recent"
 		}
 	}
 
@@ -450,20 +453,21 @@ func (a *App) initProject(name, targetDir string, template quickstartTemplate, e
 	}
 
 	result := map[string]any{
-		"action":                "init",
-		"enabledFeatures":       enabledFeatures,
-		"envPath":               quickstartResult["envPath"],
-		"metadataPath":          filepath.ToSlash(filepath.Join(localAgoraDirName, localProjectFileName)),
-		"nextSteps":             initNextSteps(template, asString(quickstartResult["path"])),
-		"path":                  quickstartResult["path"],
-		"projectAction":         projectAction,
-		"projectId":             target.project.ProjectID,
-		"projectName":           target.project.Name,
-		"region":                target.region,
-		"reusedExistingProject": projectAction == "existing",
-		"status":                "ready",
-		"template":              template.ID,
-		"title":                 template.Title,
+		"action":                 "init",
+		"enabledFeatures":        enabledFeatures,
+		"envPath":                quickstartResult["envPath"],
+		"metadataPath":           filepath.ToSlash(filepath.Join(localAgoraDirName, localProjectFileName)),
+		"nextSteps":              initNextSteps(template, asString(quickstartResult["path"])),
+		"path":                   quickstartResult["path"],
+		"projectAction":          projectAction,
+		"projectId":              target.project.ProjectID,
+		"projectName":            target.project.Name,
+		"projectSelectionReason": projectSelectionReason,
+		"region":                 target.region,
+		"reusedExistingProject":  projectAction == "existing",
+		"status":                 "ready",
+		"template":               template.ID,
+		"title":                  template.Title,
 	}
 	if createdRTMDataCenter != "" {
 		result["rtmDataCenter"] = createdRTMDataCenter
diff --git a/internal/cli/integration_help_test.go b/internal/cli/integration_help_test.go
index 45af3b7..4f1bea8 100644
--- a/internal/cli/integration_help_test.go
+++ b/internal/cli/integration_help_test.go
@@ -115,7 +115,7 @@ func TestCLIAgenticSurfaces(t *testing.T) {
 		"XDG_CONFIG_HOME": configHome,
 		"AGORA_LOG_LEVEL": "error",
 	}})
-	if introspect.exitCode != 0 || !strings.Contains(introspect.stdout, `"command":"introspect"`) || !strings.Contains(introspect.stdout, `"features":["rtc","rtm","convoai"]`) {
+	if introspect.exitCode != 0 || !strings.Contains(introspect.stdout, `"command":"introspect"`) || !strings.Contains(introspect.stdout, `"features":["rtc","rtm","convoai"]`) || !strings.Contains(introspect.stdout, `"headlessSafe":false`) || !strings.Contains(introspect.stdout, `"interactivity":"interactive-browser"`) {
 		t.Fatalf("unexpected introspect result: %+v", introspect)
 	}
 
@@ -135,3 +135,60 @@ func TestCLIAgenticSurfaces(t *testing.T) {
 		t.Fatalf("unexpected upgrade result: %+v", upgrade)
 	}
 }
+
+func TestCLIOpenRejectsConflictingBrowserFlags(t *testing.T) {
+	result := runCLI(t, []string{"open", "--target", "docs", "--browser", "--no-browser", "--json"}, cliRunOptions{
+		env: map[string]string{
+			"AGORA_HOME":      t.TempDir(),
+			"AGORA_LOG_LEVEL": "error",
+		},
+	})
+	if result.exitCode != 1 || !strings.Contains(result.stdout, `"ok":false`) || !strings.Contains(result.stdout, "choose only one of --browser or --no-browser") {
+		t.Fatalf("unexpected open conflicting flag result: %+v", result)
+	}
+}
+
+func TestAutomationDocExamplesRemainValid(t *testing.T) {
+	configHome := t.TempDir()
+	examples := []struct {
+		name       string
+		args       []string
+		wantExit   int
+		wantStdout []string
+	}{
+		{
+			name:       "introspect json",
+			args:       []string{"introspect", "--json"},
+			wantExit:   0,
+			wantStdout: []string{`"command":"introspect"`, `"commands"`},
+		},
+		{
+			name:       "auth status unauthenticated json",
+			args:       []string{"auth", "status", "--json"},
+			wantExit:   3,
+			wantStdout: []string{`"ok":false`, `"code":"AUTH_UNAUTHENTICATED"`},
+		},
+		{
+			name:       "config update explicit false syntax",
+			args:       []string{"config", "update", "--telemetry-enabled=false", "--json"},
+			wantExit:   0,
+			wantStdout: []string{`"command":"config update"`, `"telemetryEnabled":false`},
+		},
+	}
+	for _, tt := range examples {
+		t.Run(tt.name, func(t *testing.T) {
+			result := runCLI(t, tt.args, cliRunOptions{env: map[string]string{
+				"XDG_CONFIG_HOME": configHome,
+				"AGORA_LOG_LEVEL": "error",
+			}})
+			if result.exitCode != tt.wantExit {
+				t.Fatalf("automation.md example %v drifted: exit=%d want=%d stdout=%s stderr=%s. Update docs/automation.md or the example contract test.", tt.args, result.exitCode, tt.wantExit, result.stdout, result.stderr)
+			}
+			for _, want := range tt.wantStdout {
+				if !strings.Contains(result.stdout, want) {
+					t.Fatalf("automation.md example %v drifted: missing %q in stdout=%s stderr=%s. Update docs/automation.md or the example contract test.", tt.args, want, result.stdout, result.stderr)
+				}
+			}
+		})
+	}
+}
diff --git a/internal/cli/integration_init_test.go b/internal/cli/integration_init_test.go
index cf81224..e47db9e 100644
--- a/internal/cli/integration_init_test.go
+++ b/internal/cli/integration_init_test.go
@@ -68,3 +68,15 @@ func TestCLIInitCreatesProjectAndQuickstart(t *testing.T) {
 		t.Fatalf("expected init to persist current project context, got %+v", ctx)
 	}
 }
+
+func TestCLIInitRequiresTemplateWhenNoInputIsSet(t *testing.T) {
+	result := runCLI(t, []string{"init", "starter-demo", "--yes", "--json"}, cliRunOptions{
+		env: map[string]string{
+			"AGORA_HOME":      t.TempDir(),
+			"AGORA_LOG_LEVEL": "error",
+		},
+	})
+	if result.exitCode != 1 || !strings.Contains(result.stdout, `"code":"QUICKSTART_TEMPLATE_REQUIRED"`) {
+		t.Fatalf("expected QUICKSTART_TEMPLATE_REQUIRED, got %+v", result)
+	}
+}
diff --git a/internal/cli/introspect.go b/internal/cli/introspect.go
index c6be818..7082930 100644
--- a/internal/cli/introspect.go
+++ b/internal/cli/introspect.go
@@ -17,10 +17,12 @@ import (
 //	Short   — one-line description from the cobra command
 //	Flags   — local flags (inherited flags omitted to keep the tree compact)
 type commandHelpInfo struct {
-	Path    string         `json:"path"`
-	Command string         `json:"command"`
-	Short   string         `json:"short"`
-	Flags   []flagHelpInfo `json:"flags"`
+	Path          string         `json:"path"`
+	Command       string         `json:"command"`
+	Short         string         `json:"short"`
+	HeadlessSafe  bool           `json:"headlessSafe"`
+	Interactivity string         `json:"interactivity"`
+	Flags         []flagHelpInfo `json:"flags"`
 }
 
 // flagHelpInfo describes a single command-local flag in machine-readable
@@ -117,10 +119,12 @@ func buildCommandTree(root *cobra.Command) []commandHelpInfo {
 				continue
 			}
 			result = append(result, commandHelpInfo{
-				Path:    child.CommandPath(),
-				Command: strings.TrimSpace(strings.TrimPrefix(child.CommandPath(), root.CommandPath())),
-				Short:   child.Short,
-				Flags:   localFlagInfos(child),
+				Path:          child.CommandPath(),
+				Command:       strings.TrimSpace(strings.TrimPrefix(child.CommandPath(), root.CommandPath())),
+				Short:         child.Short,
+				HeadlessSafe:  commandHeadlessSafe(strings.TrimSpace(strings.TrimPrefix(child.CommandPath(), root.CommandPath()))),
+				Interactivity: commandInteractivity(strings.TrimSpace(strings.TrimPrefix(child.CommandPath(), root.CommandPath()))),
+				Flags:         localFlagInfos(child),
 			})
 			walk(child)
 		}
@@ -130,6 +134,30 @@ func buildCommandTree(root *cobra.Command) []commandHelpInfo {
 	return result
 }
 
+func commandHeadlessSafe(command string) bool {
+	switch command {
+	case "login", "auth login":
+		return false
+	default:
+		return true
+	}
+}
+
+func commandInteractivity(command string) string {
+	switch command {
+	case "login", "auth login":
+		return "interactive-browser"
+	case "mcp serve":
+		return "stdio-server"
+	case "init", "quickstart create", "project create":
+		return "headless-safe-with-required-arguments"
+	case "open":
+		return "browser-in-interactive-pretty-mode"
+	default:
+		return "none"
+	}
+}
+
 func localFlagInfos(cmd *cobra.Command) []flagHelpInfo {
 	inherited := cmd.InheritedFlags()
 	flags := make([]flagHelpInfo, 0)
diff --git a/internal/cli/mcp.go b/internal/cli/mcp.go
index 105c682..b147d98 100644
--- a/internal/cli/mcp.go
+++ b/internal/cli/mcp.go
@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"io"
 	"strings"
+	"time"
 
 	"github.com/spf13/cobra"
 )
@@ -44,6 +45,11 @@ type mcpRPCError struct {
 type mcpToolCall struct {
 	Name      string         `json:"name"`
 	Arguments map[string]any `json:"arguments"`
+	Meta      mcpCallMeta    `json:"_meta"`
+}
+
+type mcpCallMeta struct {
+	ProgressToken any `json:"progressToken"`
 }
 
 func (a *App) buildMCPCommand() *cobra.Command {
@@ -55,7 +61,8 @@ func (a *App) buildMCPCommand() *cobra.Command {
 Use this when an MCP client (Cursor, Claude Code, Windsurf, custom) wants to drive Agora workflows directly. The full Agora command surface is exposed as MCP tools so agents can authenticate, discover, manage projects, scaffold quickstarts, and run readiness checks without shelling out.
 
 Notes for agents:
-- Long-running tools (init, quickstart create, project create) emit no NDJSON progress over MCP. The result payload is returned as a single tool response.
+- Long-running tools (init, quickstart create, project create) emit MCP progress notifications when the tools/call params include _meta.progressToken.
+- Shell commands still use NDJSON progress (` + "`agora <command> --json`" + `); MCP uses JSON-RPC notifications so stdio framing remains valid.
 - ` + "`agora.auth.login`" + ` is intentionally not exposed because OAuth requires an interactive browser. Run ` + "`agora login`" + ` once on the host before starting the MCP server.
 - All tools return JSON-stringified payloads in the standard MCP ` + "`content[0].text`" + ` slot.`,
 		Example: example(`
@@ -106,7 +113,7 @@ func (a *App) serveMCP(in io.Reader, out io.Writer) error {
 		// MUST NOT receive a response. We respect that for any method,
 		// not just notifications/*.
 		isNotification := req.ID == nil
-		result, err := a.handleMCPRequest(req)
+		result, err := a.handleMCPRequest(req, encoder)
 		if isNotification {
 			continue
 		}
@@ -125,7 +132,7 @@ func (a *App) serveMCP(in io.Reader, out io.Writer) error {
 	return nil
 }
 
-func (a *App) handleMCPRequest(req mcpRequest) (any, error) {
+func (a *App) handleMCPRequest(req mcpRequest, encoder *json.Encoder) (any, error) {
 	switch req.Method {
 	case "initialize":
 		return map[string]any{
@@ -142,7 +149,7 @@ func (a *App) handleMCPRequest(req mcpRequest) (any, error) {
 		if err := json.Unmarshal(req.Params, &call); err != nil {
 			return nil, err
 		}
-		data, err := a.callMCPTool(call.Name, call.Arguments)
+		data, err := a.callMCPTool(call.Name, call.Arguments, makeMCPProgressEmitter(encoder, call.Meta.ProgressToken))
 		if err != nil {
 			return nil, err
 		}
@@ -242,6 +249,34 @@ func mcpTool(name, description string, properties map[string]string) map[string]
 	}
 }
 
+func makeMCPProgressEmitter(encoder *json.Encoder, token any) progressEmitter {
+	if encoder == nil || token == nil {
+		return nil
+	}
+	seq := 0
+	return func(stage, message string, fields map[string]any) {
+		seq++
+		params := map[string]any{
+			"progressToken": token,
+			"progress":      seq,
+			"stage":         stage,
+			"message":       message,
+			"timestamp":     time.Now().UTC().Format(time.RFC3339Nano),
+		}
+		for k, v := range fields {
+			if _, reserved := params[k]; reserved {
+				continue
+			}
+			params[k] = v
+		}
+		_ = encoder.Encode(map[string]any{
+			"jsonrpc": "2.0",
+			"method":  "notifications/progress",
+			"params":  params,
+		})
+	}
+}
+
 // callMCPTool dispatches a tool name to the underlying App method. New
 // tools must be added here in addition to mcpTools(); the switch
 // returns an explicit error for unknown names so agents see a clear
@@ -253,7 +288,7 @@ func mcpTool(name, description string, properties map[string]string) map[string]
 // when serving over stdio) is never read as if it were user input. We
 // pass bytes.NewReader(nil) and io.Discard explicitly to enforce the
 // no-stdin contract at the call site.
-func (a *App) callMCPTool(name string, args map[string]any) (any, error) {
+func (a *App) callMCPTool(name string, args map[string]any, progress progressEmitter) (any, error) {
 	switch name {
 
 	case "agora.version":
@@ -321,14 +356,20 @@ func (a *App) callMCPTool(name string, args map[string]any) (any, error) {
 		if err != nil {
 			return nil, err
 		}
-		return a.projectCreate(
+		features := stringSliceArg(args, "features")
+		progress.emit("project:create", "Creating Agora project", map[string]any{"projectName": name, "features": projectCreateFeatures(stringArg(args, "template"), features)})
+		result, err := a.projectCreate(
 			name,
 			stringArg(args, "region"),
 			stringArg(args, "template"),
-			stringSliceArg(args, "features"),
+			features,
 			rtmDataCenter,
 			stringArg(args, "idempotencyKey"),
 		)
+		if err == nil {
+			progress.emit("project:created", "Agora project ready", map[string]any{"projectId": result["projectId"], "projectName": result["projectName"]})
+		}
+		return result, err
 
 	case "agora.project.doctor":
 		return a.projectDoctor(stringArg(args, "project"), defaultString(stringArg(args, "feature"), "convoai"), boolArg(args, "deep", false)), nil
@@ -394,7 +435,7 @@ func (a *App) callMCPTool(name string, args map[string]any) (any, error) {
 		if target == "" {
 			return nil, errors.New("name or dir is required")
 		}
-		return a.quickstartCreate(*template, target, stringArg(args, "project"), stringArg(args, "ref"), nil)
+		return a.quickstartCreate(*template, target, stringArg(args, "project"), stringArg(args, "ref"), progress)
 
 	case "agora.quickstart.env_write":
 		return a.quickstartEnvWrite(defaultString(stringArg(args, "dir"), "."), stringArg(args, "template"), stringArg(args, "project"))
@@ -426,7 +467,7 @@ func (a *App) callMCPTool(name string, args map[string]any) (any, error) {
 			false,
 			&promptOut,
 			bytes.NewReader(nil),
-			nil,
+			progress,
 		)
 
 	default:
diff --git a/internal/cli/mcp_test.go b/internal/cli/mcp_test.go
index 1f07ecf..5dd04fe 100644
--- a/internal/cli/mcp_test.go
+++ b/internal/cli/mcp_test.go
@@ -3,6 +3,8 @@ package cli
 import (
 	"bytes"
 	"encoding/json"
+	"path/filepath"
+	"strconv"
 	"strings"
 	"testing"
 )
@@ -184,6 +186,35 @@ func TestMCPVersionToolReturnsBuildInfo(t *testing.T) {
 	}
 }
 
+func TestMCPQuickstartCreateEmitsProgressNotifications(t *testing.T) {
+	repo := createLocalGitRepo(t, map[string]string{
+		"env.local.example": "NEXT_PUBLIC_AGORA_APP_ID=\nNEXT_AGORA_APP_CERTIFICATE=\n",
+		"README.md":         "demo\n",
+	})
+	t.Setenv("AGORA_QUICKSTART_NEXTJS_REPO_URL", repo)
+	a := newTestApp(t)
+	target := filepath.Join(t.TempDir(), "demo")
+	frame := []byte(`{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"agora.quickstart.create","arguments":{"template":"nextjs","dir":` + strconv.Quote(target) + `},"_meta":{"progressToken":"clone-1"}}}` + "\n")
+	var out bytes.Buffer
+	if err := a.serveMCP(bytes.NewReader(frame), &out); err != nil {
+		t.Fatalf("serveMCP: %v", err)
+	}
+	lines := strings.Split(strings.TrimSpace(out.String()), "\n")
+	if len(lines) < 2 {
+		t.Fatalf("expected progress notification and final response, got: %q", out.String())
+	}
+	if !strings.Contains(lines[0], `"method":"notifications/progress"`) || !strings.Contains(lines[0], `"progressToken":"clone-1"`) || !strings.Contains(out.String(), `"stage":"clone:start"`) {
+		t.Fatalf("expected MCP progress notification, got: %q", out.String())
+	}
+	var resp mcpResponse
+	if err := json.Unmarshal([]byte(lines[len(lines)-1]), &resp); err != nil {
+		t.Fatalf("unmarshal final response: %v\nbody: %q", err, lines[len(lines)-1])
+	}
+	if resp.Error != nil {
+		t.Fatalf("unexpected final error: %+v\nall output: %q", resp.Error, out.String())
+	}
+}
+
 // TestStringSliceArgShapes verifies the MCP slice coercion handles the
 // three real-world payload shapes: native JSON array, comma-string,
 // and missing key.
diff --git a/internal/cli/quickstart.go b/internal/cli/quickstart.go
index 49d03ff..b1bb0e6 100644
--- a/internal/cli/quickstart.go
+++ b/internal/cli/quickstart.go
@@ -288,7 +288,13 @@ func (a *App) quickstartCreate(template quickstartTemplate, targetDir, explicitP
 		boundProject = &target
 	}
 
-	repoURL := a.quickstartRepoURL(template)
+	repoURL, overrideKey, err := a.quickstartRepoURL(template)
+	if err != nil {
+		return nil, err
+	}
+	if overrideKey != "" {
+		progress.emit("clone:override", fmt.Sprintf("Using repo override from %s", overrideKey), map[string]any{"repoUrl": repoURL, "envVar": overrideKey})
+	}
 	progress.emit("clone:start", "Cloning quickstart repository", map[string]any{"repoUrl": repoURL, "targetPath": absTarget, "ref": ref})
 	if err := cloneQuickstartRepo(repoURL, absTarget, ref); err != nil {
 		return nil, err
@@ -401,25 +407,51 @@ func (a *App) quickstartEnvWrite(targetDir, templateID, explicitProject string)
 	}, nil
 }
 
-func (a *App) quickstartRepoURL(template quickstartTemplate) string {
-	key := "AGORA_QUICKSTART_" + strings.ToUpper(strings.ReplaceAll(template.ID, "-", "_")) + "_REPO_URL"
+// quickstartRepoOverrideKey returns the env var name that overrides the
+// clone URL for a given template. Power users (workshops, internal forks,
+// CLI integration tests) set this; everyday users never do.
+func quickstartRepoOverrideKey(templateID string) string {
+	return "AGORA_QUICKSTART_" + strings.ToUpper(strings.ReplaceAll(templateID, "-", "_")) + "_REPO_URL"
+}
+
+// quickstartRepoURL resolves the clone URL for a template, honoring an
+// env override if present. Returns the URL, the env var name that
+// supplied the override (empty when none was used), and an error if the
+// override is set to a malformed value.
+func (a *App) quickstartRepoURL(template quickstartTemplate) (string, string, error) {
+	key := quickstartRepoOverrideKey(template.ID)
 	if override := strings.TrimSpace(a.env[key]); override != "" {
-		return override
+		if err := validateRepoOverrideURL(override); err != nil {
+			return "", "", &cliError{
+				Message: fmt.Sprintf("%s is set to an invalid value (%s): %v. Set it to an https://, ssh://, git://, file://, git@host:path, or absolute local path URL.", key, override, err),
+				Code:    "QUICKSTART_REPO_OVERRIDE_INVALID",
+			}
+		}
+		return override, key, nil
 	}
-	return template.RepoURL
+	return template.RepoURL, "", nil
 }
 
 func cloneQuickstartRepo(repoURL, targetDir, ref string) error {
-	args := []string{"clone", "--depth", "1"}
-	if strings.TrimSpace(ref) != "" {
-		args = append(args, "--branch", strings.TrimSpace(ref))
+	if err := validateGitRef(ref); err != nil {
+		return &cliError{
+			Message: fmt.Sprintf("--ref %q is invalid: %v.", ref, err),
+			Code:    "QUICKSTART_REF_INVALID",
+		}
 	}
-	args = append(args, repoURL, targetDir)
-	cmd := exec.Command("git", args...)
+	if _, err := exec.LookPath("git"); err != nil {
+		return &cliError{
+			Message: "git was not found on PATH. Install git from https://git-scm.com/downloads and retry.",
+			Code:    "QUICKSTART_GIT_MISSING",
+		}
+	}
+	// #nosec G204 -- git is invoked without a shell; repoURL and targetDir
+	// follow "--" so git cannot parse them as flags.
+	cmd := exec.Command("git", gitQuickstartCloneArgs(repoURL, targetDir, ref)...)
 	output, err := cmd.CombinedOutput()
 	if err != nil {
 		trimmed := strings.TrimSpace(string(output))
-		hint := "Ensure git is installed and you have network access to GitHub."
+		hint := "Check network access to the host and that the ref exists."
 		if trimmed == "" {
 			return fmt.Errorf("git clone failed for %s. %s", repoURL, hint)
 		}
@@ -428,6 +460,64 @@ func cloneQuickstartRepo(repoURL, targetDir, ref string) error {
 	return nil
 }
 
+// validateGitRef rejects ref values that would either confuse git's
+// option parser or are obviously malformed. Empty refs are allowed and
+// mean "default branch."
+func validateGitRef(ref string) error {
+	trimmed := strings.TrimSpace(ref)
+	if trimmed == "" {
+		return nil
+	}
+	if strings.HasPrefix(trimmed, "-") {
+		return fmt.Errorf("must not start with '-'")
+	}
+	for _, r := range trimmed {
+		if r == ' ' || r == '\t' || r < 0x20 || r == 0x7f {
+			return fmt.Errorf("must not contain whitespace or control characters")
+		}
+	}
+	return nil
+}
+
+// validateRepoOverrideURL accepts the URL forms git itself accepts for
+// remotes plus absolute local paths used by the integration tests. It
+// rejects values that begin with '-' to keep them from being parsed as
+// git options even before "--" terminates argv.
+func validateRepoOverrideURL(s string) error {
+	if s == "" {
+		return fmt.Errorf("must not be empty")
+	}
+	if strings.HasPrefix(s, "-") {
+		return fmt.Errorf("must not start with '-'")
+	}
+	for _, scheme := range []string{"http://", "https://", "ssh://", "git://", "file://"} {
+		if strings.HasPrefix(s, scheme) {
+			return nil
+		}
+	}
+	if at := strings.Index(s, "@"); at > 0 {
+		if strings.Contains(s[at+1:], ":") {
+			return nil
+		}
+	}
+	if filepath.IsAbs(s) {
+		return nil
+	}
+	return fmt.Errorf("unrecognized URL form")
+}
+
+func gitQuickstartCloneArgs(repoURL, targetDir, ref string) []string {
+	// Disable credential helpers for this invocation so non-TTY agent/CI runs
+	// do not consult macOS keychain for public HTTPS repos.
+	args := []string{"-c", "credential.helper=", "clone", "--depth", "1"}
+	if strings.TrimSpace(ref) != "" {
+		args = append(args, "--branch", strings.TrimSpace(ref))
+	}
+	// "--" stops git from treating repoURL/targetDir as flags if they start with "-".
+	args = append(args, "--", repoURL, targetDir)
+	return args
+}
+
 func (a *App) resolveOptionalProjectTarget(explicitProject, startPath string) (projectTarget, bool, error) {
 	if strings.TrimSpace(explicitProject) != "" {
 		target, err := a.resolveProjectTargetFrom(explicitProject, startPath)
diff --git a/internal/cli/quickstart_test.go b/internal/cli/quickstart_test.go
new file mode 100644
index 0000000..a4a82fa
--- /dev/null
+++ b/internal/cli/quickstart_test.go
@@ -0,0 +1,155 @@
+package cli
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+)
+
+func TestGitQuickstartCloneArgs(t *testing.T) {
+	args := gitQuickstartCloneArgs("https://github.com/AgoraIO/example", "/tmp/example", "")
+	want := []string{"-c", "credential.helper=", "clone", "--depth", "1", "--", "https://github.com/AgoraIO/example", "/tmp/example"}
+	if !reflect.DeepEqual(args, want) {
+		t.Fatalf("unexpected clone args:\n got: %#v\nwant: %#v", args, want)
+	}
+
+	args = gitQuickstartCloneArgs("https://github.com/AgoraIO/example", "/tmp/example", " release/v1 ")
+	want = []string{"-c", "credential.helper=", "clone", "--depth", "1", "--branch", "release/v1", "--", "https://github.com/AgoraIO/example", "/tmp/example"}
+	if !reflect.DeepEqual(args, want) {
+		t.Fatalf("unexpected clone args with ref:\n got: %#v\nwant: %#v", args, want)
+	}
+
+	args = gitQuickstartCloneArgs("-https://evil.example/repo", "/tmp/example", "")
+	want = []string{"-c", "credential.helper=", "clone", "--depth", "1", "--", "-https://evil.example/repo", "/tmp/example"}
+	if !reflect.DeepEqual(args, want) {
+		t.Fatalf("unexpected clone args with dash-prefixed url:\n got: %#v\nwant: %#v", args, want)
+	}
+}
+
+func TestCloneQuickstartRepoLocal(t *testing.T) {
+	repo := createLocalGitRepo(t, map[string]string{
+		"README.md": "# Quickstart\n",
+	})
+	target := filepath.Join(t.TempDir(), "quickstart")
+
+	if err := cloneQuickstartRepo(repo, target, ""); err != nil {
+		t.Fatalf("cloneQuickstartRepo failed: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(target, ".git")); err != nil {
+		t.Fatalf("expected cloned git repo: %v", err)
+	}
+}
+
+func TestCloneQuickstartRepoRejectsBadRef(t *testing.T) {
+	target := filepath.Join(t.TempDir(), "quickstart")
+	err := cloneQuickstartRepo("https://example.invalid/repo.git", target, "-fexploit")
+	if err == nil {
+		t.Fatal("expected error for dash-prefixed ref, got nil")
+	}
+	var cliErr *cliError
+	if !errors.As(err, &cliErr) {
+		t.Fatalf("expected *cliError, got %T: %v", err, err)
+	}
+	if cliErr.Code != "QUICKSTART_REF_INVALID" {
+		t.Fatalf("expected code QUICKSTART_REF_INVALID, got %q", cliErr.Code)
+	}
+	if _, statErr := os.Stat(target); !os.IsNotExist(statErr) {
+		t.Fatalf("expected target not created on validation failure, stat err = %v", statErr)
+	}
+}
+
+func TestValidateGitRef(t *testing.T) {
+	cases := []struct {
+		name string
+		ref  string
+		ok   bool
+	}{
+		{"empty allowed", "", true},
+		{"whitespace allowed (treated as empty)", "  ", true},
+		{"normal branch", "main", true},
+		{"slash branch", "release/v1", true},
+		{"tag with dots", "v1.2.3", true},
+		{"leading dash rejected", "-fexploit", false},
+		{"embedded space rejected", "release v1", false},
+		{"embedded tab rejected", "release\tv1", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateGitRef(tc.ref)
+			if tc.ok && err != nil {
+				t.Fatalf("expected ref %q to be valid, got error: %v", tc.ref, err)
+			}
+			if !tc.ok && err == nil {
+				t.Fatalf("expected ref %q to be rejected", tc.ref)
+			}
+		})
+	}
+}
+
+func TestValidateRepoOverrideURL(t *testing.T) {
+	localAbsPath := filepath.Join(os.TempDir(), "example-repo")
+	cases := []struct {
+		name string
+		url  string
+		ok   bool
+	}{
+		{"https", "https://github.com/AgoraIO/example", true},
+		{"http", "http://example.com/repo.git", true},
+		{"ssh", "ssh://git@github.com/AgoraIO/example.git", true},
+		{"git", "git://github.com/AgoraIO/example.git", true},
+		{"file", "file:///srv/mirror/example.git", true},
+		{"ssh shorthand", "git@github.com:AgoraIO/example.git", true},
+		{"absolute local path", localAbsPath, true},
+		{"empty rejected", "", false},
+		{"dash prefix rejected", "-https://evil/repo", false},
+		{"unrecognized form rejected", "example", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateRepoOverrideURL(tc.url)
+			if tc.ok && err != nil {
+				t.Fatalf("expected %q to be valid, got error: %v", tc.url, err)
+			}
+			if !tc.ok && err == nil {
+				t.Fatalf("expected %q to be rejected", tc.url)
+			}
+		})
+	}
+}
+
+func TestQuickstartRepoOverrideKey(t *testing.T) {
+	if got := quickstartRepoOverrideKey("nextjs"); got != "AGORA_QUICKSTART_NEXTJS_REPO_URL" {
+		t.Fatalf("unexpected key for nextjs: %q", got)
+	}
+	if got := quickstartRepoOverrideKey("my-template"); got != "AGORA_QUICKSTART_MY_TEMPLATE_REPO_URL" {
+		t.Fatalf("unexpected key for my-template: %q", got)
+	}
+}
+
+func TestQuickstartRepoURLOverride(t *testing.T) {
+	tmpl := quickstartTemplate{ID: "nextjs", RepoURL: "https://default.example/repo"}
+	app := &App{env: map[string]string{}}
+
+	url, override, err := app.quickstartRepoURL(tmpl)
+	if err != nil || override != "" || url != tmpl.RepoURL {
+		t.Fatalf("default path: url=%q override=%q err=%v", url, override, err)
+	}
+
+	app.env = map[string]string{"AGORA_QUICKSTART_NEXTJS_REPO_URL": "https://fork.example/repo"}
+	url, override, err = app.quickstartRepoURL(tmpl)
+	if err != nil || override != "AGORA_QUICKSTART_NEXTJS_REPO_URL" || url != "https://fork.example/repo" {
+		t.Fatalf("override path: url=%q override=%q err=%v", url, override, err)
+	}
+
+	app.env = map[string]string{"AGORA_QUICKSTART_NEXTJS_REPO_URL": "-fexploit"}
+	if _, _, err := app.quickstartRepoURL(tmpl); err == nil {
+		t.Fatal("expected error for invalid override")
+	} else {
+		var cliErr *cliError
+		if !errors.As(err, &cliErr) || cliErr.Code != "QUICKSTART_REPO_OVERRIDE_INVALID" {
+			t.Fatalf("expected QUICKSTART_REPO_OVERRIDE_INVALID, got %v", err)
+		}
+	}
+}
diff --git a/internal/cli/skills.go b/internal/cli/skills.go
index 88672f4..03d37ce 100644
--- a/internal/cli/skills.go
+++ b/internal/cli/skills.go
@@ -39,7 +39,7 @@ func skillsCatalog() []skill {
 			Tags:        []string{"nextjs", "rtc", "video", "init"},
 			Steps: []string{
 				"agora login",
-				"agora init my-nextjs-demo --template nextjs --json",
+				"agora init my-nextjs-demo --template nextjs --new-project --json",
 				"cd my-nextjs-demo && npm install && npm run dev",
 			},
 			NextSteps: []string{
@@ -56,7 +56,7 @@ func skillsCatalog() []skill {
 			Tags:        []string{"python", "convoai", "voice", "init"},
 			Steps: []string{
 				"agora login",
-				"agora init my-voice-agent --template python --feature convoai --json",
+				"agora init my-voice-agent --template python --new-project --feature convoai --json",
 				"cd my-voice-agent/server && pip install -r requirements.txt",
 			},
 			NextSteps: []string{
@@ -72,7 +72,7 @@ func skillsCatalog() []skill {
 			Tags:        []string{"go", "rtc", "token", "backend", "init"},
 			Steps: []string{
 				"agora login",
-				"agora init my-go-token-service --template go --feature rtc --json",
+				"agora init my-go-token-service --template go --new-project --feature rtc --json",
 				"cd my-go-token-service/server-go && go run .",
 			},
 			NextSteps: []string{
@@ -117,6 +117,7 @@ func skillsCatalog() []skill {
 				"agora login  # MCP does not expose OAuth; authenticate on the host first",
 				"agora mcp serve  # smoke test that it speaks MCP",
 				"In your IDE settings, add a server that runs 'agora mcp serve'.",
+				"For stage-level progress, pass _meta.progressToken in MCP tools/call params or shell out with 'agora init ... --json'.",
 			},
 			DocsURL: "https://agoraio.github.io/cli/md/agents/README.md",
 		},
diff --git a/internal/cli/upgrade.go b/internal/cli/upgrade.go
index d74bc46..a91d27a 100644
--- a/internal/cli/upgrade.go
+++ b/internal/cli/upgrade.go
@@ -78,6 +78,12 @@ func (a *App) performSelfUpdate(dryRun bool) (map[string]any, error) {
 		result["status"] = "manual"
 		return result, nil
 	}
+	if !dryRun && isCIEnvironment(a.osEnv) && !truthyEnv(a.osEnv, "AGORA_ALLOW_UPGRADE_IN_CI") {
+		result["status"] = "manual"
+		result["ciBlocked"] = true
+		result["suggestedCommand"] = "agora upgrade --check --json"
+		return result, nil
+	}
 
 	// Resolve the latest release tag from GitHub.
 	latest, err := resolveLatestVersion(a.env)
@@ -118,7 +124,7 @@ func (a *App) performSelfUpdate(dryRun bool) (map[string]any, error) {
 
 	goos := runtime.GOOS
 	goarch := runtime.GOARCH
-	archiveName, ext, err := upgradeArchiveName(latest, goos, goarch)
+	candidates, err := upgradeArchiveCandidates(latest, goos, goarch)
 	if err != nil {
 		return nil, &cliError{Message: err.Error(), Code: "UPGRADE_UNSUPPORTED_PLATFORM"}
 	}
@@ -132,35 +138,49 @@ func (a *App) performSelfUpdate(dryRun bool) (map[string]any, error) {
 		baseURL = fmt.Sprintf("https://github.com/%s/releases/download", repo)
 	}
 
-	archiveURL := fmt.Sprintf("%s/v%s/%s", baseURL, latest, archiveName)
 	checksumsURL := fmt.Sprintf("%s/v%s/checksums.txt", baseURL, latest)
-
-	archivePath := filepath.Join(tmpDir, archiveName)
-	if err := downloadFile(archiveURL, archivePath, a.env); err != nil {
-		return nil, &cliError{Message: fmt.Sprintf("could not download %s: %v", archiveURL, err), Code: "UPGRADE_DOWNLOAD_FAILED"}
-	}
 	checksumsPath := filepath.Join(tmpDir, "checksums.txt")
 	if err := downloadFile(checksumsURL, checksumsPath, a.env); err != nil {
 		return nil, &cliError{Message: fmt.Sprintf("could not download %s: %v", checksumsURL, err), Code: "UPGRADE_DOWNLOAD_FAILED"}
 	}
 
-	// Verify SHA-256.
-	expected, err := expectedChecksumFor(checksumsPath, archiveName)
-	if err != nil {
-		return nil, &cliError{Message: fmt.Sprintf("could not parse checksums: %v", err), Code: "UPGRADE_CHECKSUM_FAILED"}
-	}
-	if expected == "" {
-		return nil, &cliError{Message: fmt.Sprintf("checksum for %s not found in checksums.txt", archiveName), Code: "UPGRADE_CHECKSUM_FAILED"}
-	}
-	actual, err := sha256OfFile(archivePath)
-	if err != nil {
-		return nil, &cliError{Message: fmt.Sprintf("could not hash downloaded archive: %v", err), Code: "UPGRADE_CHECKSUM_FAILED"}
+	var ext string
+	var archivePath string
+	var downloadErr error
+	for _, candidate := range candidates {
+		candidateURL := fmt.Sprintf("%s/v%s/%s", baseURL, latest, candidate.name)
+		candidatePath := filepath.Join(tmpDir, candidate.name)
+		if err := downloadFile(candidateURL, candidatePath, a.env); err != nil {
+			downloadErr = err
+			continue
+		}
+		expected, err := expectedChecksumFor(checksumsPath, candidate.name)
+		if err != nil {
+			return nil, &cliError{Message: fmt.Sprintf("could not parse checksums: %v", err), Code: "UPGRADE_CHECKSUM_FAILED"}
+		}
+		if expected == "" {
+			downloadErr = fmt.Errorf("checksum for %s not found in checksums.txt", candidate.name)
+			continue
+		}
+		actual, err := sha256OfFile(candidatePath)
+		if err != nil {
+			return nil, &cliError{Message: fmt.Sprintf("could not hash downloaded archive: %v", err), Code: "UPGRADE_CHECKSUM_FAILED"}
+		}
+		if !strings.EqualFold(expected, actual) {
+			return nil, &cliError{
+				Message: fmt.Sprintf("checksum mismatch for %s; expected %s, got %s", candidate.name, expected, actual),
+				Code:    "UPGRADE_CHECKSUM_FAILED",
+			}
+		}
+		ext = candidate.ext
+		archivePath = candidatePath
+		break
 	}
-	if !strings.EqualFold(expected, actual) {
-		return nil, &cliError{
-			Message: fmt.Sprintf("checksum mismatch for %s; expected %s, got %s", archiveName, expected, actual),
-			Code:    "UPGRADE_CHECKSUM_FAILED",
+	if archivePath == "" {
+		if downloadErr == nil {
+			downloadErr = errors.New("no matching release archive found")
 		}
+		return nil, &cliError{Message: fmt.Sprintf("could not download a verified release archive: %v", downloadErr), Code: "UPGRADE_DOWNLOAD_FAILED"}
 	}
 
 	// Extract the new binary to a temp file next to the running one.
@@ -378,15 +398,48 @@ func upgradeCommandForInstallMethod(method string) string {
 	}
 }
 
-// upgradeArchiveName returns the GoReleaser archive filename for the given
-// version + platform and its extension ("tar.gz" or "zip"). It mirrors the
-// naming in .goreleaser.yaml.
-func upgradeArchiveName(version, goos, goarch string) (string, string, error) {
+type upgradeArchiveCandidate struct {
+	name string
+	ext  string
+}
+
+const legacyReleaseArchiveFirstVersion = "0.1.7"
+
+// releaseUsesLegacyArchiveNaming reports whether a published GitHub release
+// shipped archives under the historical agora-cli-go_* prefix (v0.1.7–v0.2.0).
+func releaseUsesLegacyArchiveNaming(version string) bool {
+	version = strings.TrimPrefix(strings.TrimSpace(version), "v")
+	if version == "" || version == "dev" {
+		return false
+	}
+	return isSameOrNewer(version, legacyReleaseArchiveFirstVersion) &&
+		!isSameOrNewer(version, "0.2.1")
+}
+
+// upgradeArchiveCandidates returns the archive filename(s) to try for a target
+// release version. Releases from v0.2.1 onward use agora-cli_* only; v0.1.7
+// through v0.2.0 used agora-cli-go_*.
+func upgradeArchiveCandidates(version, goos, goarch string) ([]upgradeArchiveCandidate, error) {
+	if releaseUsesLegacyArchiveNaming(version) {
+		legacy, ext, err := releaseArchiveFileName("agora-cli-go", version, goos, goarch)
+		if err != nil {
+			return nil, err
+		}
+		return []upgradeArchiveCandidate{{name: legacy, ext: ext}}, nil
+	}
+	primary, ext, err := releaseArchiveFileName("agora-cli", version, goos, goarch)
+	if err != nil {
+		return nil, err
+	}
+	return []upgradeArchiveCandidate{{name: primary, ext: ext}}, nil
+}
+
+func releaseArchiveFileName(prefix, version, goos, goarch string) (string, string, error) {
 	switch goos {
 	case "windows":
-		return fmt.Sprintf("agora-cli-go_v%s_%s_%s.zip", version, goos, goarch), "zip", nil
+		return fmt.Sprintf("%s_v%s_%s_%s.zip", prefix, version, goos, goarch), "zip", nil
 	case "darwin", "linux":
-		return fmt.Sprintf("agora-cli-go_v%s_%s_%s.tar.gz", version, goos, goarch), "tar.gz", nil
+		return fmt.Sprintf("%s_v%s_%s_%s.tar.gz", prefix, version, goos, goarch), "tar.gz", nil
 	default:
 		return "", "", fmt.Errorf("self-update is not supported on %s/%s; use the platform installer", goos, goarch)
 	}
diff --git a/internal/cli/upgrade_test.go b/internal/cli/upgrade_test.go
new file mode 100644
index 0000000..5120053
--- /dev/null
+++ b/internal/cli/upgrade_test.go
@@ -0,0 +1,42 @@
+package cli
+
+import "testing"
+
+func TestReleaseUsesLegacyArchiveNaming(t *testing.T) {
+	tests := []struct {
+		version string
+		want    bool
+	}{
+		{version: "0.1.6", want: false},
+		{version: "0.1.7", want: true},
+		{version: "0.2.0", want: true},
+		{version: "0.2.1", want: false},
+		{version: "0.3.0", want: false},
+		{version: "v0.2.0", want: true},
+	}
+	for _, tt := range tests {
+		if got := releaseUsesLegacyArchiveNaming(tt.version); got != tt.want {
+			t.Fatalf("releaseUsesLegacyArchiveNaming(%q) = %v, want %v", tt.version, got, tt.want)
+		}
+	}
+}
+
+func TestUpgradeArchiveCandidatesUsesNewNamingFrom021(t *testing.T) {
+	candidates, err := upgradeArchiveCandidates("0.2.1", "linux", "amd64")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(candidates) != 1 || candidates[0].name != "agora-cli_v0.2.1_linux_amd64.tar.gz" {
+		t.Fatalf("unexpected candidates: %+v", candidates)
+	}
+}
+
+func TestUpgradeArchiveCandidatesUsesLegacyNamingThrough020(t *testing.T) {
+	candidates, err := upgradeArchiveCandidates("0.2.0", "linux", "amd64")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(candidates) != 1 || candidates[0].name != "agora-cli-go_v0.2.0_linux_amd64.tar.gz" {
+		t.Fatalf("unexpected candidates: %+v", candidates)
+	}
+}
diff --git a/internal/cli/version.go b/internal/cli/version.go
index b87865e..fb2da83 100644
--- a/internal/cli/version.go
+++ b/internal/cli/version.go
@@ -5,7 +5,7 @@ import "fmt"
 // Build-time injected version variables. These are populated by ldflags at
 // release time:
 //
-//	go build -ldflags '-X github.com/.../internal/cli.version=v0.2.0
+//	go build -ldflags '-X github.com/.../internal/cli.version=v0.2.1
 //	                    -X github.com/.../internal/cli.commit=abc1234
 //	                    -X github.com/.../internal/cli.date=2026-05-05'
 //
diff --git a/main.go b/main.go
index 29afd11..8012014 100644
--- a/main.go
+++ b/main.go
@@ -4,7 +4,7 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/agora/cli-workspace/agora-cli-go/internal/cli"
+	"github.com/AgoraIO/cli/internal/cli"
 )
 
 func main() {
diff --git a/packaging/npm/agoraio-cli-darwin-arm64/package.json b/packaging/npm/agoraio-cli-darwin-arm64/package.json
index bf0f142..dbeea5a 100644
--- a/packaging/npm/agoraio-cli-darwin-arm64/package.json
+++ b/packaging/npm/agoraio-cli-darwin-arm64/package.json
@@ -9,7 +9,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AgoraIO/cli.git",
-    "directory": "agora-cli-go/packaging/npm/agoraio-cli-darwin-arm64"
+    "directory": "packaging/npm/agoraio-cli-darwin-arm64"
   },
   "license": "MIT",
   "author": "Agora DevRel <devrel@agora.io>",
diff --git a/packaging/npm/agoraio-cli-darwin-x64/package.json b/packaging/npm/agoraio-cli-darwin-x64/package.json
index c7b466d..536afae 100644
--- a/packaging/npm/agoraio-cli-darwin-x64/package.json
+++ b/packaging/npm/agoraio-cli-darwin-x64/package.json
@@ -9,7 +9,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AgoraIO/cli.git",
-    "directory": "agora-cli-go/packaging/npm/agoraio-cli-darwin-x64"
+    "directory": "packaging/npm/agoraio-cli-darwin-x64"
   },
   "license": "MIT",
   "author": "Agora DevRel <devrel@agora.io>",
diff --git a/packaging/npm/agoraio-cli-linux-arm64/package.json b/packaging/npm/agoraio-cli-linux-arm64/package.json
index 43ac514..68d01e1 100644
--- a/packaging/npm/agoraio-cli-linux-arm64/package.json
+++ b/packaging/npm/agoraio-cli-linux-arm64/package.json
@@ -9,7 +9,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AgoraIO/cli.git",
-    "directory": "agora-cli-go/packaging/npm/agoraio-cli-linux-arm64"
+    "directory": "packaging/npm/agoraio-cli-linux-arm64"
   },
   "license": "MIT",
   "author": "Agora DevRel <devrel@agora.io>",
diff --git a/packaging/npm/agoraio-cli-linux-x64/package.json b/packaging/npm/agoraio-cli-linux-x64/package.json
index 2d87151..18998ca 100644
--- a/packaging/npm/agoraio-cli-linux-x64/package.json
+++ b/packaging/npm/agoraio-cli-linux-x64/package.json
@@ -9,7 +9,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AgoraIO/cli.git",
-    "directory": "agora-cli-go/packaging/npm/agoraio-cli-linux-x64"
+    "directory": "packaging/npm/agoraio-cli-linux-x64"
   },
   "license": "MIT",
   "author": "Agora DevRel <devrel@agora.io>",
diff --git a/packaging/npm/agoraio-cli-win32-arm64/package.json b/packaging/npm/agoraio-cli-win32-arm64/package.json
index 1870875..324baed 100644
--- a/packaging/npm/agoraio-cli-win32-arm64/package.json
+++ b/packaging/npm/agoraio-cli-win32-arm64/package.json
@@ -9,7 +9,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AgoraIO/cli.git",
-    "directory": "agora-cli-go/packaging/npm/agoraio-cli-win32-arm64"
+    "directory": "packaging/npm/agoraio-cli-win32-arm64"
   },
   "license": "MIT",
   "author": "Agora DevRel <devrel@agora.io>",
diff --git a/packaging/npm/agoraio-cli-win32-x64/package.json b/packaging/npm/agoraio-cli-win32-x64/package.json
index 6183981..41cce07 100644
--- a/packaging/npm/agoraio-cli-win32-x64/package.json
+++ b/packaging/npm/agoraio-cli-win32-x64/package.json
@@ -9,7 +9,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AgoraIO/cli.git",
-    "directory": "agora-cli-go/packaging/npm/agoraio-cli-win32-x64"
+    "directory": "packaging/npm/agoraio-cli-win32-x64"
   },
   "license": "MIT",
   "author": "Agora DevRel <devrel@agora.io>",
diff --git a/packaging/npm/agoraio-cli/package.json b/packaging/npm/agoraio-cli/package.json
index accd4a3..c547e12 100644
--- a/packaging/npm/agoraio-cli/package.json
+++ b/packaging/npm/agoraio-cli/package.json
@@ -9,7 +9,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AgoraIO/cli.git",
-    "directory": "agora-cli-go/packaging/npm/agoraio-cli"
+    "directory": "packaging/npm/agoraio-cli"
   },
   "license": "MIT",
   "author": "Agora DevRel <devrel@agora.io>",