From c064bc2a68d0a4c7d615c3f74abb858ad0692feb Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Tue, 19 May 2026 17:04:09 -0400
Subject: [PATCH 01/22] fix quickstart git clone credential handling

Disable git credential helpers for quickstart clone subprocesses so init and quickstart create work in non-interactive agent and CI environments.
---
 internal/cli/quickstart.go      | 18 +++++++++++------
 internal/cli/quickstart_test.go | 36 +++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 6 deletions(-)
 create mode 100644 internal/cli/quickstart_test.go

diff --git a/internal/cli/quickstart.go b/internal/cli/quickstart.go
index 49d03ff..547edc4 100644
--- a/internal/cli/quickstart.go
+++ b/internal/cli/quickstart.go
@@ -410,12 +410,7 @@ func (a *App) quickstartRepoURL(template quickstartTemplate) string {
 }
 
 func cloneQuickstartRepo(repoURL, targetDir, ref string) error {
-	args := []string{"clone", "--depth", "1"}
-	if strings.TrimSpace(ref) != "" {
-		args = append(args, "--branch", strings.TrimSpace(ref))
-	}
-	args = append(args, repoURL, targetDir)
-	cmd := exec.Command("git", args...)
+	cmd := exec.Command("git", gitQuickstartCloneArgs(repoURL, targetDir, ref)...)
 	output, err := cmd.CombinedOutput()
 	if err != nil {
 		trimmed := strings.TrimSpace(string(output))
@@ -428,6 +423,17 @@ func cloneQuickstartRepo(repoURL, targetDir, ref string) error {
 	return nil
 }
 
+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))
+	}
+	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..0172e47
--- /dev/null
+++ b/internal/cli/quickstart_test.go
@@ -0,0 +1,36 @@
+package cli
+
+import (
+	"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)
+	}
+}
+
+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)
+	}
+}

From 257cf26c7008f3255b73108fadc99b5ee725e0ad Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Tue, 19 May 2026 17:05:00 -0400
Subject: [PATCH 02/22] chore: bump GitHub Actions versions in workflows

Update checkout, deploy-pages, Docker setup, and setup-node actions to their latest major releases across CI, release, pages, and govulncheck workflows.
---
 .github/workflows/apt-repo.yml    |  2 +-
 .github/workflows/ci.yml          |  2 +-
 .github/workflows/govulncheck.yml |  2 +-
 .github/workflows/pages.yml       |  4 ++--
 .github/workflows/release.yml     | 12 ++++++------
 5 files changed, 11 insertions(+), 11 deletions(-)

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..f8fd6c5 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
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..74db9f0 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"

From 2e55c8eed141b0b773b52f03fa9719f5499530b6 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Tue, 19 May 2026 17:07:32 -0400
Subject: [PATCH 03/22] chore: release v0.2.1

Prepare the 0.2.1 patch release in the changelog and version metadata.
---
 CHANGELOG.md            | 9 ++++++++-
 internal/cli/version.go | 2 +-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b2a9258..82a4cba 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,12 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-19
+
+### 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.
+
 ## [0.2.0] - 2026-05-05
 
 ### Added
@@ -199,7 +205,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/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'
 //

From ad8135df56ada88e03c0f3b35ef504cc81bf02a0 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Tue, 19 May 2026 17:24:57 -0400
Subject: [PATCH 04/22] fix: harden quickstart clone with friendly errors and
 override visibility

Validate --ref and AGORA_QUICKSTART_<TEMPLATE>_REPO_URL overrides up front,
pre-flight git on PATH, and emit a clone:override progress event so workshop
and CI runs can see which fork was cloned. Adds error codes
QUICKSTART_REF_INVALID, QUICKSTART_REPO_OVERRIDE_INVALID, and
QUICKSTART_GIT_MISSING.
---
 CHANGELOG.md                    |   7 ++
 docs/automation.md              |   1 +
 docs/error-codes.md             |   3 +
 internal/cli/env_help.go        |   1 +
 internal/cli/quickstart.go      |  98 ++++++++++++++++++++++++--
 internal/cli/quickstart_test.go | 118 +++++++++++++++++++++++++++++++-
 6 files changed, 219 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82a4cba..1e0453e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,9 +17,16 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [0.2.1] - 2026-05-19
 
+### 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.
+
 ### 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.
 
 ## [0.2.0] - 2026-05-05
 
diff --git a/docs/automation.md b/docs/automation.md
index d97393d..69a3a48 100644
--- a/docs/automation.md
+++ b/docs/automation.md
@@ -200,6 +200,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` |
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/internal/cli/env_help.go b/internal/cli/env_help.go
index 8640b76..2fe17f2 100644
--- a/internal/cli/env_help.go
+++ b/internal/cli/env_help.go
@@ -46,6 +46,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/quickstart.go b/internal/cli/quickstart.go
index 547edc4..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,20 +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 {
+	if err := validateGitRef(ref); err != nil {
+		return &cliError{
+			Message: fmt.Sprintf("--ref %q is invalid: %v.", ref, err),
+			Code:    "QUICKSTART_REF_INVALID",
+		}
+	}
+	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)
 		}
@@ -423,6 +460,52 @@ 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.
@@ -430,7 +513,8 @@ func gitQuickstartCloneArgs(repoURL, targetDir, ref string) []string {
 	if strings.TrimSpace(ref) != "" {
 		args = append(args, "--branch", strings.TrimSpace(ref))
 	}
-	args = append(args, repoURL, targetDir)
+	// "--" stops git from treating repoURL/targetDir as flags if they start with "-".
+	args = append(args, "--", repoURL, targetDir)
 	return args
 }
 
diff --git a/internal/cli/quickstart_test.go b/internal/cli/quickstart_test.go
index 0172e47..bb307b8 100644
--- a/internal/cli/quickstart_test.go
+++ b/internal/cli/quickstart_test.go
@@ -9,16 +9,22 @@ import (
 
 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"}
+	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"}
+	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) {
@@ -34,3 +40,111 @@ func TestCloneQuickstartRepoLocal(t *testing.T) {
 		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")
+	}
+	cliErr, ok := err.(*cliError)
+	if !ok {
+		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) {
+	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", "/tmp/example-repo", 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 if cliErr, ok := err.(*cliError); !ok || cliErr.Code != "QUICKSTART_REPO_OVERRIDE_INVALID" {
+		t.Fatalf("expected QUICKSTART_REPO_OVERRIDE_INVALID, got %v", err)
+	}
+}

From c98769f327667d76d283ee80d0640c1a0a3e2379 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Tue, 19 May 2026 17:27:20 -0400
Subject: [PATCH 05/22] updated troubleshooting docs

---
 docs/troubleshooting.md | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index e5566ca..cef938d 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
+```
+
+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
 ```
 
-If `git` is missing, install it (Homebrew, apt, winget, etc.). If
-network access fails, check proxies and corporate firewall rules.
+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"
 

From 23e47ebadeb2d29f912b330f602a481d1dc18c90 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 11:51:03 -0400
Subject: [PATCH 06/22] fix: harden CLI automation defaults for CI and agents

Require --template for non-interactive init runs, add projectSelectionReason
to init JSON output, default agora open to URL-only in CI/non-TTY sessions
with explicit --browser/--no-browser control, and block installer self-update
in CI unless AGORA_ALLOW_UPGRADE_IN_CI is set.
---
 docs/commands.md                      |  3 +-
 docs/troubleshooting.md               | 12 ++++++++
 internal/cli/commands.go              | 20 ++++++++++--
 internal/cli/env_help.go              |  1 +
 internal/cli/init.go                  | 44 +++++++++++++++------------
 internal/cli/integration_help_test.go | 12 ++++++++
 internal/cli/integration_init_test.go | 12 ++++++++
 internal/cli/upgrade.go               |  6 ++++
 8 files changed, 86 insertions(+), 24 deletions(-)

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/troubleshooting.md b/docs/troubleshooting.md
index cef938d..58a3845 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -131,6 +131,18 @@ 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
+```
+
+For package-manager installs, use the package manager's own upgrade command.
+
 ## Output looks wrong in scripts (color codes, table widths)
 
 The CLI auto-detects CI and disables color and progress bars there. In
diff --git a/internal/cli/commands.go b/internal/cli/commands.go
index db1faeb..932e7a1 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
 }
 
diff --git a/internal/cli/env_help.go b/internal/cli/env_help.go
index 2fe17f2..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"},
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..51ceaf2 100644
--- a/internal/cli/integration_help_test.go
+++ b/internal/cli/integration_help_test.go
@@ -135,3 +135,15 @@ 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)
+	}
+}
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/upgrade.go b/internal/cli/upgrade.go
index d74bc46..1493de7 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)

From 584be44e1af67ac0a9774619aa9846c811ae0839 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 11:57:39 -0400
Subject: [PATCH 07/22] docs: expand agent and automation guidance

Document MCP progress caveats, headless CI init patterns, projectSelectionReason
and upgrade ciBlocked fields in automation.md, expand llms.txt for agents, and
update skills/MCP help with deterministic --new-project init examples.
---
 AGENTS.md              |  3 ++-
 docs/agents/README.md  |  6 +++---
 docs/automation.md     | 14 +++++++++++++-
 docs/llms.txt          | 24 +++++++++++++++++++++---
 internal/cli/mcp.go    |  1 +
 internal/cli/skills.go |  7 ++++---
 6 files changed, 44 insertions(+), 11 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 4d4d85d..fdc6b91 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -219,7 +219,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)
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/automation.md b/docs/automation.md
index 69a3a48..5120c84 100644
--- a/docs/automation.md
+++ b/docs/automation.md
@@ -39,10 +39,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.
 
@@ -241,6 +242,7 @@ 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.
 - 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.
+- If you need per-stage progress and cancellation hooks, run the same workflow via shell commands (`agora ... --json`) and parse NDJSON locally.
 
 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.
 
@@ -289,6 +291,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`
@@ -301,6 +304,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.
@@ -922,6 +927,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.
@@ -949,9 +956,14 @@ 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`
+- 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/llms.txt b/docs/llms.txt
index 86b5871..97fe23a 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,23 @@ 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 caveat**: Long-running tools over MCP return a single final response; NDJSON progress stages are not streamed over MCP.
+- **When progress matters**: shell out directly (for example `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.
+- `--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`.
+
 ## Common Use Cases
 
 ### Login and Authentication
@@ -57,8 +74,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 +106,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/internal/cli/mcp.go b/internal/cli/mcp.go
index 105c682..9af62ad 100644
--- a/internal/cli/mcp.go
+++ b/internal/cli/mcp.go
@@ -56,6 +56,7 @@ Use this when an MCP client (Cursor, Claude Code, Windsurf, custom) wants to dri
 
 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.
+- If you need stage-level progress hooks, shell out to ` + "`agora <command> --json`" + ` and parse NDJSON directly instead of using MCP for that step.
 - ` + "`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(`
diff --git a/internal/cli/skills.go b/internal/cli/skills.go
index 88672f4..7ceabd5 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'.",
+				"If you need stage-level progress, run shell commands like 'agora init ... --json' instead of MCP tools.",
 			},
 			DocsURL: "https://agoraio.github.io/cli/md/agents/README.md",
 		},

From 4d2c7d37d4a13ebd962a03db74b917a91279593c Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:09:51 -0400
Subject: [PATCH 08/22] fix: align module path and rename release archives to
 agora-cli

Point go.mod and build ldflags at github.com/AgoraIO/cli, publish agora-cli_*
archives as the primary release artifact, keep agora-cli-go_* as a legacy alias,
and teach agora upgrade and the install scripts to prefer the new name with
fallback for older installs.
---
 .github/workflows/ci.yml      |  4 +-
 .github/workflows/release.yml |  6 +--
 .goreleaser.yaml              | 21 ++++++--
 cmd/gendocs/main.go           |  2 +-
 docs/install.md               |  4 +-
 go.mod                        |  2 +-
 install.ps1                   |  2 +-
 install.sh                    |  2 +-
 internal/cli/upgrade.go       | 97 +++++++++++++++++++++++++----------
 internal/cli/upgrade_test.go  | 19 +++++++
 main.go                       |  2 +-
 11 files changed, 116 insertions(+), 45 deletions(-)
 create mode 100644 internal/cli/upgrade_test.go

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f8fd6c5..dcbeb82 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -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/release.yml b/.github/workflows/release.yml
index 74db9f0..ed4dc9f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -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..0b877ee 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -20,14 +20,25 @@ 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.
+# A legacy alias (agora-cli-go_*) is also published so older installed
+# binaries whose embedded upgrade logic only knows the previous prefix can
+# still self-update — the same self-healing idea as always fetching install.sh.
 archives:
   - id: agora-cli
+    ids: [agora-cli]
+    name_template: 'agora-cli_{{ .Tag }}_{{ .Os }}_{{ .Arch }}'
+    formats:
+      - tar.gz
+    format_overrides:
+      - goos: windows
+        formats:
+          - zip
+  - id: agora-cli-legacy-alias
     ids: [agora-cli]
     name_template: 'agora-cli-go_{{ .Tag }}_{{ .Os }}_{{ .Arch }}'
     formats:
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/install.md b/docs/install.md
index 3b07a01..7808ebe 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -346,8 +346,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.0_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.0_linux_amd64.tar.gz.spdx.json
 ```
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/upgrade.go b/internal/cli/upgrade.go
index 1493de7..bf366d7 100644
--- a/internal/cli/upgrade.go
+++ b/internal/cli/upgrade.go
@@ -124,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"}
 	}
@@ -138,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.
@@ -384,20 +398,47 @@ 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
+}
+
+// upgradeArchiveCandidates returns release archive filenames to try, newest
+// naming first. Legacy agora-cli-go_* names remain published as release
+// aliases (see .goreleaser.yaml) so older binaries and this fallback both
+// work across the rename.
+func upgradeArchiveCandidates(version, goos, goarch string) ([]upgradeArchiveCandidate, error) {
+	primary, ext, err := releaseArchiveFileName("agora-cli", version, goos, goarch)
+	if err != nil {
+		return nil, err
+	}
+	legacy, _, err := releaseArchiveFileName("agora-cli-go", version, goos, goarch)
+	if err != nil {
+		return nil, err
+	}
+	return []upgradeArchiveCandidate{
+		{name: primary, ext: ext},
+		{name: legacy, 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)
 	}
 }
 
+// upgradeArchiveName returns the current GoReleaser archive filename for the
+// given version + platform and its extension ("tar.gz" or "zip").
+func upgradeArchiveName(version, goos, goarch string) (string, string, error) {
+	return releaseArchiveFileName("agora-cli", version, goos, goarch)
+}
+
 // resolveLatestVersion queries the GitHub API for the latest release tag and
 // returns the bare version (no leading "v"). Honors GITHUB_API_URL and
 // GITHUB_TOKEN/GH_TOKEN for testing and rate-limit relief.
diff --git a/internal/cli/upgrade_test.go b/internal/cli/upgrade_test.go
new file mode 100644
index 0000000..03682f0
--- /dev/null
+++ b/internal/cli/upgrade_test.go
@@ -0,0 +1,19 @@
+package cli
+
+import "testing"
+
+func TestUpgradeArchiveCandidatesPreferNewNaming(t *testing.T) {
+	candidates, err := upgradeArchiveCandidates("0.2.1", "linux", "amd64")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(candidates) != 2 {
+		t.Fatalf("expected 2 candidates, got %d", len(candidates))
+	}
+	if candidates[0].name != "agora-cli_v0.2.1_linux_amd64.tar.gz" {
+		t.Fatalf("unexpected primary archive name: %q", candidates[0].name)
+	}
+	if candidates[1].name != "agora-cli-go_v0.2.1_linux_amd64.tar.gz" {
+		t.Fatalf("unexpected legacy archive name: %q", candidates[1].name)
+	}
+}
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() {

From 0486ddd36b56f03c2bf07d964aa06d6d6856c4f1 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:10:26 -0400
Subject: [PATCH 09/22] docs: align contributor and npm paths with repo root
 layout

Fix CONTRIBUTING clone instructions to cd cli/, update npm package
repository.directory metadata, point the issue template docs link at docs/,
and mark the devex backlog contributor-path item shipped.
---
 .github/ISSUE_TEMPLATE/config.yml                   |  2 +-
 CONTRIBUTING.md                                     |  3 +--
 docs/devex-backlog.md                               | 10 ++++++----
 packaging/npm/agoraio-cli-darwin-arm64/package.json |  2 +-
 packaging/npm/agoraio-cli-darwin-x64/package.json   |  2 +-
 packaging/npm/agoraio-cli-linux-arm64/package.json  |  2 +-
 packaging/npm/agoraio-cli-linux-x64/package.json    |  2 +-
 packaging/npm/agoraio-cli-win32-arm64/package.json  |  2 +-
 packaging/npm/agoraio-cli-win32-x64/package.json    |  2 +-
 packaging/npm/agoraio-cli/package.json              |  2 +-
 10 files changed, 15 insertions(+), 14 deletions(-)

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/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/docs/devex-backlog.md b/docs/devex-backlog.md
index 2150cac..948bfd4 100644
--- a/docs/devex-backlog.md
+++ b/docs/devex-backlog.md
@@ -21,7 +21,9 @@ Update this file as items ship or priorities change.
 
 ### 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.
+**Status:** Shipped (2026-05-20).
+
+**Problem (resolved):** Contributor docs previously referenced workspace-only paths such as `cd cli/agora-cli-go`. The canonical public layout is clone `AgoraIO/cli`, then `cd cli/`.
 
 **Target files**
 
@@ -30,9 +32,9 @@ Update this file as items ship or priorities change.
 
 **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.
+- [x] Paths match the **actual** default layout of `github.com/AgoraIO/cli` (`git clone … && cd cli/`).
+- [x] No workspace-only subdirectory names (for example `agora-cli-go/`) in contributor setup instructions.
+- [x] `make test` / `go build` instructions run verbatim from a fresh clone.
 
 ---
 
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>",

From 4dcf43e0fe8b5af11b5a193851fb36c52e1b58fb Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:10:57 -0400
Subject: [PATCH 10/22] fix: version-aware upgrade archive naming and release
 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Select agora-cli-go_* archives only for v0.1.7–v0.2.0 targets and agora-cli_*
for v0.2.1+, drop the redundant legacy alias from GoReleaser, and document
upgrade paths, install examples, and the v0.2.1 release summary.
---
 .github/ISSUE_TEMPLATE/bug_report.yml |  2 +-
 .goreleaser.yaml                      | 12 ------
 AGENTS.md                             |  4 +-
 README.md                             |  2 +-
 RELEASING.md                          | 10 +++--
 docs/automation.md                    |  1 +
 docs/install.md                       | 29 +++++++++-----
 docs/llms.txt                         |  4 +-
 docs/releases/v0.2.1.md               | 55 +++++++++++++++++++++++++++
 docs/troubleshooting.md               | 30 +++++++++++++++
 internal/cli/upgrade.go               | 36 ++++++++++++------
 internal/cli/upgrade_test.go          | 37 ++++++++++++++----
 12 files changed, 174 insertions(+), 48 deletions(-)
 create mode 100644 docs/releases/v0.2.1.md

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/.goreleaser.yaml b/.goreleaser.yaml
index 0b877ee..8f21dc2 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -25,9 +25,6 @@ builds:
       - -X github.com/AgoraIO/cli/internal/cli.date={{ .Date }}
 
 # Archive naming matches install.sh, install.ps1, and agora upgrade self-update.
-# A legacy alias (agora-cli-go_*) is also published so older installed
-# binaries whose embedded upgrade logic only knows the previous prefix can
-# still self-update — the same self-healing idea as always fetching install.sh.
 archives:
   - id: agora-cli
     ids: [agora-cli]
@@ -38,15 +35,6 @@ archives:
       - goos: windows
         formats:
           - zip
-  - id: agora-cli-legacy-alias
-    ids: [agora-cli]
-    name_template: 'agora-cli-go_{{ .Tag }}_{{ .Os }}_{{ .Arch }}'
-    formats:
-      - tar.gz
-    format_overrides:
-      - goos: windows
-        formats:
-          - zip
 
 checksum:
   name_template: checksums.txt
diff --git a/AGENTS.md b/AGENTS.md
index fdc6b91..eab207e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -209,7 +209,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
 
@@ -249,7 +249,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/README.md b/README.md
index aa8abac..67ec3fd 100644
--- a/README.md
+++ b/README.md
@@ -308,7 +308,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..bb1d411 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. Optionally add a curated summary at `docs/releases/v<version>.md` and paste it into the GitHub release description alongside GoReleaser's auto-generated commit list.
+
 ## Local Verification
 
 Before cutting a tag:
diff --git a/docs/automation.md b/docs/automation.md
index 5120c84..e757887 100644
--- a/docs/automation.md
+++ b/docs/automation.md
@@ -963,6 +963,7 @@ Optional fields:
 
 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/install.md b/docs/install.md
index 7808ebe..c1da099 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -22,7 +22,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 +64,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 +144,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 +206,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 +254,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 +282,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 +333,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 +357,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_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_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 97fe23a..348f3e6 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -57,9 +57,11 @@ Check project health: agora project doctor --json
 
 - 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`.
+- 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
 
diff --git a/docs/releases/v0.2.1.md b/docs/releases/v0.2.1.md
new file mode 100644
index 0000000..71f897d
--- /dev/null
+++ b/docs/releases/v0.2.1.md
@@ -0,0 +1,55 @@
+# Agora CLI v0.2.1
+
+Patch release focused on agent/CI automation reliability, quickstart clone hardening, and release-artifact naming cleanup.
+
+## Highlights
+
+- **Headless-safe defaults** — `agora open` no longer auto-launches a browser in CI or non-TTY sessions; `agora upgrade` skips in-place self-update in CI unless explicitly opted in.
+- **Deterministic init** — `agora init --yes` now requires `--template` and returns `projectSelectionReason` in JSON for agent branching.
+- **Quickstart clone fixes** — git credential helpers disabled for public clones; friendly error codes for missing git, bad refs, and malformed repo overrides; `clone:override` progress when env overrides are active.
+- **Release archive rename** — GitHub release assets are now `agora-cli_v*` (was `agora-cli-go_v*` for v0.1.7–v0.2.0).
+
+## Upgrade notes
+
+### Direct installer (`install.sh` / `install.ps1`)
+
+Fresh installs and re-runs of the installer always fetch the latest install script and the correct archive name — no action needed.
+
+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 embed upgrade logic that only knows 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.). No archive-name change affects 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.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
+agora --version
+```
+
+Or pin this release:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --version 0.2.1
+```
+
+## Full changelog
+
+See [CHANGELOG.md](../../CHANGELOG.md#021---2026-05-20) for the complete list of changes.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 58a3845..51103e6 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -141,8 +141,38 @@ 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
diff --git a/internal/cli/upgrade.go b/internal/cli/upgrade.go
index bf366d7..6b7f4a4 100644
--- a/internal/cli/upgrade.go
+++ b/internal/cli/upgrade.go
@@ -403,23 +403,35 @@ type upgradeArchiveCandidate struct {
 	ext  string
 }
 
-// upgradeArchiveCandidates returns release archive filenames to try, newest
-// naming first. Legacy agora-cli-go_* names remain published as release
-// aliases (see .goreleaser.yaml) so older binaries and this fallback both
-// work across the rename.
+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) {
-	primary, ext, err := releaseArchiveFileName("agora-cli", version, goos, goarch)
-	if err != nil {
-		return nil, err
+	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
 	}
-	legacy, _, err := releaseArchiveFileName("agora-cli-go", version, goos, goarch)
+	primary, ext, err := releaseArchiveFileName("agora-cli", version, goos, goarch)
 	if err != nil {
 		return nil, err
 	}
-	return []upgradeArchiveCandidate{
-		{name: primary, ext: ext},
-		{name: legacy, ext: ext},
-	}, nil
+	return []upgradeArchiveCandidate{{name: primary, ext: ext}}, nil
 }
 
 func releaseArchiveFileName(prefix, version, goos, goarch string) (string, string, error) {
diff --git a/internal/cli/upgrade_test.go b/internal/cli/upgrade_test.go
index 03682f0..5120053 100644
--- a/internal/cli/upgrade_test.go
+++ b/internal/cli/upgrade_test.go
@@ -2,18 +2,41 @@ package cli
 
 import "testing"
 
-func TestUpgradeArchiveCandidatesPreferNewNaming(t *testing.T) {
+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) != 2 {
-		t.Fatalf("expected 2 candidates, got %d", len(candidates))
+	if len(candidates) != 1 || candidates[0].name != "agora-cli_v0.2.1_linux_amd64.tar.gz" {
+		t.Fatalf("unexpected candidates: %+v", candidates)
 	}
-	if candidates[0].name != "agora-cli_v0.2.1_linux_amd64.tar.gz" {
-		t.Fatalf("unexpected primary archive name: %q", candidates[0].name)
+}
+
+func TestUpgradeArchiveCandidatesUsesLegacyNamingThrough020(t *testing.T) {
+	candidates, err := upgradeArchiveCandidates("0.2.0", "linux", "amd64")
+	if err != nil {
+		t.Fatal(err)
 	}
-	if candidates[1].name != "agora-cli-go_v0.2.1_linux_amd64.tar.gz" {
-		t.Fatalf("unexpected legacy archive name: %q", candidates[1].name)
+	if len(candidates) != 1 || candidates[0].name != "agora-cli-go_v0.2.0_linux_amd64.tar.gz" {
+		t.Fatalf("unexpected candidates: %+v", candidates)
 	}
 }

From e8c301261f2687407e8f670802c8692027d69cd3 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:11:24 -0400
Subject: [PATCH 11/22] chore: finalize v0.2.1 release notes in CHANGELOG

Consolidate all v0.2.1 changes under a single release section with updated
date, automation/upgrade/archive entries, and a link to docs/releases/v0.2.1.md.
---
 CHANGELOG.md | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e0453e..c0995f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,19 +15,39 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [Unreleased]
 
-## [0.2.1] - 2026-05-19
+## [0.2.1] - 2026-05-20
+
+Automation hardening, quickstart reliability fixes, and release-artifact rename. See [docs/releases/v0.2.1.md](docs/releases/v0.2.1.md) for the GitHub release summary.
 
 ### 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.
 
+### 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.
 
+### 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 caveat in `agora mcp serve` help and the skills catalog.
+- 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.
+- Add v0.2.1 release notes at `docs/releases/v0.2.1.md` and document archive naming / upgrade migration in `docs/install.md` and `docs/troubleshooting.md`.
+
 ## [0.2.0] - 2026-05-05
 
 ### Added

From 4da2e6ae8a6d279d882e15d1f72604c587a15367 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:58:18 -0400
Subject: [PATCH 12/22] feat: forward MCP progress notifications for
 long-running tools

Emit JSON-RPC notifications/progress when tools/call includes
_meta.progressToken. Wire progress through init, quickstart create,
and project create without writing NDJSON to the stdio transport.
---
 internal/cli/mcp.go      | 60 +++++++++++++++++++++++++++++++++-------
 internal/cli/mcp_test.go | 31 +++++++++++++++++++++
 internal/cli/skills.go   |  2 +-
 3 files changed, 82 insertions(+), 11 deletions(-)

diff --git a/internal/cli/mcp.go b/internal/cli/mcp.go
index 9af62ad..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,8 +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.
-- If you need stage-level progress hooks, shell out to ` + "`agora <command> --json`" + ` and parse NDJSON directly instead of using MCP for that step.
+- 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(`
@@ -107,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
 		}
@@ -126,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{
@@ -143,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
 		}
@@ -243,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
@@ -254,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":
@@ -322,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
@@ -395,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"))
@@ -427,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/skills.go b/internal/cli/skills.go
index 7ceabd5..03d37ce 100644
--- a/internal/cli/skills.go
+++ b/internal/cli/skills.go
@@ -117,7 +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'.",
-				"If you need stage-level progress, run shell commands like 'agora init ... --json' instead of MCP tools.",
+				"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",
 		},

From b4a7f963b73c8720b341c535dd871de5314b41c0 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:58:42 -0400
Subject: [PATCH 13/22] feat: add headlessSafe and interactivity fields to
 introspect JSON

Expose per-command automation hints so agents can tell which commands
require a browser or explicit arguments without inferring from help text.
---
 internal/cli/introspect.go | 44 +++++++++++++++++++++++++++++++-------
 1 file changed, 36 insertions(+), 8 deletions(-)

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)

From e734e31c5014ad8398c564c50c5b581767d0c121 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:59:00 -0400
Subject: [PATCH 14/22] feat: hint when project env prints raw stdout in pretty
 TTY mode

Print a stderr tip pointing callers at --json or --format envelope when
the default dotenv output is used interactively without an explicit format.
---
 internal/cli/commands.go | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/internal/cli/commands.go b/internal/cli/commands.go
index 932e7a1..191cd03 100644
--- a/internal/cli/commands.go
+++ b/internal/cli/commands.go
@@ -792,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
 		},
 	}

From c24b097a639117645da1ff47b1ce2b2cdc442e2c Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:59:18 -0400
Subject: [PATCH 15/22] test: cover introspect metadata and automation doc CLI
 examples

Assert headlessSafe/interactivity in introspect output and exercise
representative commands documented in automation.md to catch doc drift.
---
 internal/cli/integration_help_test.go | 47 ++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/internal/cli/integration_help_test.go b/internal/cli/integration_help_test.go
index 51ceaf2..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)
 	}
 
@@ -147,3 +147,48 @@ func TestCLIOpenRejectsConflictingBrowserFlags(t *testing.T) {
 		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)
+				}
+			}
+		})
+	}
+}

From c885043b79d31e9a2ca93cdc2a792306fb2f9bb1 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:59:35 -0400
Subject: [PATCH 16/22] docs: expand automation contract for MCP, login, and
 envelope rules

Document MCP progress tokens, login NDJSON parsing, envelope versioning,
project env behavior, and config boolean flag syntax.
---
 AGENTS.md               |  1 +
 docs/automation.md      | 70 ++++++++++++++++++++++++++++++++++++-----
 docs/llms.txt           |  4 +--
 docs/troubleshooting.md | 12 +++++++
 4 files changed, 78 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index eab207e..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
 
diff --git a/docs/automation.md b/docs/automation.md
index e757887..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)
@@ -148,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)
@@ -175,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`.
@@ -231,20 +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.
 
-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.
+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":"..."}}
+```
+
+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.
-- If you need per-stage progress and cancellation hooks, run the same workflow via shell commands (`agora ... --json`) and parse NDJSON locally.
-
-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:
 
@@ -281,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:
@@ -740,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`.
@@ -915,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`
diff --git a/docs/llms.txt b/docs/llms.txt
index 348f3e6..d875887 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -48,8 +48,8 @@ Check project health: agora project doctor --json
 
 - **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 caveat**: Long-running tools over MCP return a single final response; NDJSON progress stages are not streamed over MCP.
-- **When progress matters**: shell out directly (for example `agora init ... --json`) and parse stdout line-by-line (progress events + final envelope).
+- **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.
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 51103e6..4d332f6 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -235,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)

From b11b9c4df79cc9c9b3b565fb8848fddec7635726 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 12:59:58 -0400
Subject: [PATCH 17/22] docs: surface enterprise install paths in README and
 install guide

Add npm, manual tarball, and checksum verification options for
environments that block pipe-to-shell installers.
---
 README.md       |  2 ++
 docs/install.md | 16 ++++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/README.md b/README.md
index 67ec3fd..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.
diff --git a/docs/install.md b/docs/install.md
index c1da099..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

From 07003ddcc2c76b233296ea6c958f9e68a7235243 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 13:00:16 -0400
Subject: [PATCH 18/22] docs: add skip link for GitHub Pages keyboard
 navigation

---
 docs/_layouts/default.html |  1 +
 docs/assets/css/site.css   | 16 ++++++++++++++++
 2 files changed, 17 insertions(+)

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/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;

From 6c6437a8a65bdbca66382dd6b9efc22cbb20ba81 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Wed, 20 May 2026 13:00:44 -0400
Subject: [PATCH 19/22] chore: consolidate v0.2.1 notes and drop docs/releases
 summaries

Fold upgrade notes into CHANGELOG.md and point RELEASING.md at the
changelog as the single release-notes source.
---
 CHANGELOG.md            | 34 ++++++++++++++++++++++---
 RELEASING.md            |  2 +-
 docs/releases/v0.2.1.md | 55 -----------------------------------------
 3 files changed, 32 insertions(+), 59 deletions(-)
 delete mode 100644 docs/releases/v0.2.1.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c0995f3..780299d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,12 +17,15 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [0.2.1] - 2026-05-20
 
-Automation hardening, quickstart reliability fixes, and release-artifact rename. See [docs/releases/v0.2.1.md](docs/releases/v0.2.1.md) for the GitHub release summary.
+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
 
@@ -38,15 +41,40 @@ Automation hardening, quickstart reliability fixes, and release-artifact rename.
 - 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 caveat in `agora mcp serve` help and the skills catalog.
+- 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.
-- Add v0.2.1 release notes at `docs/releases/v0.2.1.md` and document archive naming / upgrade migration in `docs/install.md` and `docs/troubleshooting.md`.
+- 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
 
diff --git a/RELEASING.md b/RELEASING.md
index bb1d411..024798c 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -35,7 +35,7 @@ The release workflow (`.github/workflows/release.yml`) then:
 
 ## Release notes
 
-Before tagging, ensure [CHANGELOG.md](CHANGELOG.md) has the version section finalized. Optionally add a curated summary at `docs/releases/v<version>.md` and paste it into the GitHub release description alongside GoReleaser's auto-generated commit list.
+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
 
diff --git a/docs/releases/v0.2.1.md b/docs/releases/v0.2.1.md
deleted file mode 100644
index 71f897d..0000000
--- a/docs/releases/v0.2.1.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# Agora CLI v0.2.1
-
-Patch release focused on agent/CI automation reliability, quickstart clone hardening, and release-artifact naming cleanup.
-
-## Highlights
-
-- **Headless-safe defaults** — `agora open` no longer auto-launches a browser in CI or non-TTY sessions; `agora upgrade` skips in-place self-update in CI unless explicitly opted in.
-- **Deterministic init** — `agora init --yes` now requires `--template` and returns `projectSelectionReason` in JSON for agent branching.
-- **Quickstart clone fixes** — git credential helpers disabled for public clones; friendly error codes for missing git, bad refs, and malformed repo overrides; `clone:override` progress when env overrides are active.
-- **Release archive rename** — GitHub release assets are now `agora-cli_v*` (was `agora-cli-go_v*` for v0.1.7–v0.2.0).
-
-## Upgrade notes
-
-### Direct installer (`install.sh` / `install.ps1`)
-
-Fresh installs and re-runs of the installer always fetch the latest install script and the correct archive name — no action needed.
-
-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 embed upgrade logic that only knows 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.). No archive-name change affects 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.
-
-## Install
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
-agora --version
-```
-
-Or pin this release:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --version 0.2.1
-```
-
-## Full changelog
-
-See [CHANGELOG.md](../../CHANGELOG.md#021---2026-05-20) for the complete list of changes.

From eb3dcc607a0cb4078d4d822a464951ea5b6ef7a3 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Thu, 21 May 2026 17:16:23 -0400
Subject: [PATCH 20/22] removed stale files

---
 docs/devex-backlog.md | 159 ------------------------------------------
 1 file changed, 159 deletions(-)
 delete mode 100644 docs/devex-backlog.md

diff --git a/docs/devex-backlog.md b/docs/devex-backlog.md
deleted file mode 100644
index 948bfd4..0000000
--- a/docs/devex-backlog.md
+++ /dev/null
@@ -1,159 +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
-
-**Status:** Shipped (2026-05-20).
-
-**Problem (resolved):** Contributor docs previously referenced workspace-only paths such as `cd cli/agora-cli-go`. The canonical public layout is clone `AgoraIO/cli`, then `cd cli/`.
-
-**Target files**
-
-- [`CONTRIBUTING.md`](../CONTRIBUTING.md)
-- Optionally [`README.md`](../README.md) “Build from source” if it duplicates the path
-
-**Acceptance criteria**
-
-- [x] Paths match the **actual** default layout of `github.com/AgoraIO/cli` (`git clone … && cd cli/`).
-- [x] No workspace-only subdirectory names (for example `agora-cli-go/`) in contributor setup instructions.
-- [x] `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. |

From c93c0d6b046cef87be97e2439a7e5cfa77e2fa61 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Thu, 21 May 2026 17:16:57 -0400
Subject: [PATCH 21/22] removed unused functions, fix lint error

---
 internal/cli/quickstart_test.go | 12 ++++++++----
 internal/cli/upgrade.go         |  6 ------
 2 files changed, 8 insertions(+), 10 deletions(-)

diff --git a/internal/cli/quickstart_test.go b/internal/cli/quickstart_test.go
index bb307b8..b4cbfee 100644
--- a/internal/cli/quickstart_test.go
+++ b/internal/cli/quickstart_test.go
@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"errors"
 	"os"
 	"path/filepath"
 	"reflect"
@@ -47,8 +48,8 @@ func TestCloneQuickstartRepoRejectsBadRef(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for dash-prefixed ref, got nil")
 	}
-	cliErr, ok := err.(*cliError)
-	if !ok {
+	var cliErr *cliError
+	if !errors.As(err, &cliErr) {
 		t.Fatalf("expected *cliError, got %T: %v", err, err)
 	}
 	if cliErr.Code != "QUICKSTART_REF_INVALID" {
@@ -144,7 +145,10 @@ func TestQuickstartRepoURLOverride(t *testing.T) {
 	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 if cliErr, ok := err.(*cliError); !ok || cliErr.Code != "QUICKSTART_REPO_OVERRIDE_INVALID" {
-		t.Fatalf("expected QUICKSTART_REPO_OVERRIDE_INVALID, got %v", err)
+	} 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/upgrade.go b/internal/cli/upgrade.go
index 6b7f4a4..a91d27a 100644
--- a/internal/cli/upgrade.go
+++ b/internal/cli/upgrade.go
@@ -445,12 +445,6 @@ func releaseArchiveFileName(prefix, version, goos, goarch string) (string, strin
 	}
 }
 
-// upgradeArchiveName returns the current GoReleaser archive filename for the
-// given version + platform and its extension ("tar.gz" or "zip").
-func upgradeArchiveName(version, goos, goarch string) (string, string, error) {
-	return releaseArchiveFileName("agora-cli", version, goos, goarch)
-}
-
 // resolveLatestVersion queries the GitHub API for the latest release tag and
 // returns the bare version (no leading "v"). Honors GITHUB_API_URL and
 // GITHUB_TOKEN/GH_TOKEN for testing and rate-limit relief.

From fe90d747544cfffc38b3b6a8a628e932908321b1 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Thu, 21 May 2026 17:19:40 -0400
Subject: [PATCH 22/22] fix to use platform-agnostic absolute path

---
 internal/cli/quickstart_test.go | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/internal/cli/quickstart_test.go b/internal/cli/quickstart_test.go
index b4cbfee..a4a82fa 100644
--- a/internal/cli/quickstart_test.go
+++ b/internal/cli/quickstart_test.go
@@ -89,6 +89,7 @@ func TestValidateGitRef(t *testing.T) {
 }
 
 func TestValidateRepoOverrideURL(t *testing.T) {
+	localAbsPath := filepath.Join(os.TempDir(), "example-repo")
 	cases := []struct {
 		name string
 		url  string
@@ -100,7 +101,7 @@ func TestValidateRepoOverrideURL(t *testing.T) {
 		{"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", "/tmp/example-repo", true},
+		{"absolute local path", localAbsPath, true},
 		{"empty rejected", "", false},
 		{"dash prefix rejected", "-https://evil/repo", false},
 		{"unrecognized form rejected", "example", false},