Release/v0.2.1

.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
 

.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.

.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

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -136,7 +136,7 @@ jobs:
           download_dir="$fixture_root/download/v${version}"
           install_dir="$PWD/.tmp/install-bin"
           bad_install_dir="$PWD/.tmp/install-bin-bad"
-          archive="agora-cli-go_v${version}_${goos}_${goarch}.tar.gz"
+          archive="agora-cli_v${version}_${goos}_${goarch}.tar.gz"
 
           rm -rf "$fixture_root" "$install_dir" "$bad_install_dir"
           mkdir -p "$download_dir"
@@ -191,7 +191,7 @@ jobs:
           $downloadDir = Join-Path $fixtureRoot "download/v$version"
           $installDir = Join-Path $PWD '.tmp/install-bin'
           $badInstallDir = Join-Path $PWD '.tmp/install-bin-bad'
-          $archive = "agora-cli-go_v$version" + "_windows_${arch}.zip"
+          $archive = "agora-cli_v$version" + "_windows_${arch}.zip"
 
           Remove-Item -Recurse -Force $fixtureRoot, $installDir, $badInstallDir -ErrorAction SilentlyContinue
           New-Item -ItemType Directory -Force -Path $downloadDir | Out-Null

.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

.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
 

.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0   # GoReleaser needs full history for changelog
 
@@ -57,13 +57,13 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -107,10 +107,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "20"
           registry-url: "https://registry.npmjs.org"
@@ -159,7 +159,7 @@ jobs:
           set -euo pipefail
           mkdir -p dist
           gh release download "${{ steps.ver.outputs.tag }}" \
-            --pattern "agora-cli-go_*" \
+            --pattern "agora-cli_*" \
             --pattern "checksums.txt" \
             --dir dist
           echo "Downloaded artifacts:"
@@ -183,7 +183,7 @@ jobs:
             file="$(echo "$line" | awk '{print $2}')"
             # Only verify our archive files (not e.g. .deb/.rpm we don't repackage).
             case "$file" in
-              agora-cli-go_*_linux_*.tar.gz|agora-cli-go_*_darwin_*.tar.gz|agora-cli-go_*_windows_*.zip) ;;
+              agora-cli_*_linux_*.tar.gz|agora-cli_*_darwin_*.tar.gz|agora-cli_*_windows_*.zip) ;;
               *) continue ;;
             esac
             if [ ! -f "$file" ]; then
@@ -211,7 +211,7 @@ jobs:
           stage_platform() {
             local goos="$1" goarch="$2" npm_pkg="$3" bin_name="$4" archive_ext="$5"
             local pkg_dir="packaging/npm/${npm_pkg}"
-            local archive="agora-cli-go_${tag}_${goos}_${goarch}.${archive_ext}"
+            local archive="agora-cli_${tag}_${goos}_${goarch}.${archive_ext}"
 
             mkdir -p "${pkg_dir}/bin"
             if [ "$archive_ext" = "zip" ]; then

.goreleaser.yaml

@@ -20,16 +20,15 @@ builds:
       - -trimpath
     ldflags:
       - -s -w
-      - -X github.com/agora/cli-workspace/agora-cli-go/internal/cli.version={{ .Version }}
-      - -X github.com/agora/cli-workspace/agora-cli-go/internal/cli.commit={{ .ShortCommit }}
-      - -X github.com/agora/cli-workspace/agora-cli-go/internal/cli.date={{ .Date }}
+      - -X github.com/AgoraIO/cli/internal/cli.version={{ .Version }}
+      - -X github.com/AgoraIO/cli/internal/cli.commit={{ .ShortCommit }}
+      - -X github.com/AgoraIO/cli/internal/cli.date={{ .Date }}
 
-# Preserve existing archive naming so install scripts (and future package managers)
-# continue to work without changes.
+# Archive naming matches install.sh, install.ps1, and agora upgrade self-update.
 archives:
   - id: agora-cli
     ids: [agora-cli]
-    name_template: 'agora-cli-go_{{ .Tag }}_{{ .Os }}_{{ .Arch }}'
+    name_template: 'agora-cli_{{ .Tag }}_{{ .Os }}_{{ .Arch }}'
     formats:
       - tar.gz
     format_overrides:

AGENTS.md

@@ -200,6 +200,7 @@ When adding a command:
 4. Add the command to the README command model
 5. Add a stable JSON result shape to `docs/automation.md`
 6. Call out breaking JSON or exit-code changes in `CHANGELOG.md` and migration notes in `docs/automation.md` when behavior is intentional.
+7. If the command is exposed through MCP, update `mcpTools()` and refresh the compact tool-surface summary in `docs/llms.txt`.
 
 ## CI and Release
 
@@ -209,7 +210,7 @@ When adding a command:
 | `release.yml` | `v*` tag | Builds cross-platform binaries, publishes GitHub release and package channels |
 | `apt-repo.yml` | published release | Updates the signed apt repository |
 
-Tagging `v0.2.0` (or any `v*` semver tag) triggers the release workflow automatically.
+Tagging `v0.2.1` (or any `v*` semver tag) triggers the release workflow automatically.
 
 ## Gotchas
 
@@ -219,7 +220,8 @@ Tagging `v0.2.0` (or any `v*` semver tag) triggers the release workflow automati
 | Headless OAuth | Use `--no-browser` to print a URL instead of opening a browser |
 | `quickstart env write` ≠ `project env write` | Template-aware paths and variable names vs generic dotenv block |
 | `add` namespace | Reserved and hidden; must behave as not-found from the user's perspective |
-| `doctor --deep` | Flag exists but deep checks are not fully implemented; don't document as stable yet |
+| `doctor --deep` | Stable workspace checks for `.agora` metadata and quickstart env consistency; prefer `--deep --json` in repo-bound automation. |
+| `open` browser launch | Auto-open happens only in interactive pretty TTY sessions outside CI. Use `--browser` to force opening or `--no-browser` for URL-only behavior. |
 | App certificate required | `quickstart env write` and `init` fail env injection if the project has no certificate |
 
 ## npm Distribution (Node Wrapper)
@@ -248,7 +250,7 @@ packaging/npm/
 3. If the platform package is missing, the shim prints a helpful error pointing to Homebrew or GitHub releases
 
 **Release flow (automated and active):** the `publish-npm` job in `release.yml`:
-1. Downloads release archives and `checksums.txt` from the GitHub release
+1. Downloads release archives (`agora-cli_v*`, v0.2.1+) and `checksums.txt` from the GitHub release
 2. Verifies SHA-256 of every archive against `checksums.txt`; fails the job on mismatch
 3. Extracts the binary for each platform into the corresponding package's `bin/`
 4. Stamps the tag version into all `package.json` files (wrapper + 6 platform packages, including `optionalDependencies` values)

CHANGELOG.md

@@ -15,6 +15,67 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-05-20
+
+Automation hardening, quickstart reliability fixes, agent introspection and MCP progress improvements, and release-artifact rename.
+
+### Added
+
+- Emit a `clone:override` progress event when `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL` overrides the clone URL, so workshop and CI runs can confirm which fork they cloned.
+- Document `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL` in `agora env-help` and the automation reference.
+- Add MCP `notifications/progress` forwarding for long-running tools when clients pass `_meta.progressToken`.
+- Add `headlessSafe` and `interactivity` metadata to `agora introspect --json` command records.
+- Add automation contract tests for representative `docs/automation.md` examples.
+
+### Changed
+
+- `agora open` now defaults to URL-only behavior in CI and non-TTY sessions (unless `--browser` is explicitly passed), and adds explicit `--browser` / `--no-browser` conflict validation.
+- `agora init` now requires `--template` in non-interactive (`--yes`) runs instead of silently selecting the first available template; init JSON output now includes `projectSelectionReason` for deterministic agent branching.
+- Block installer-managed `agora upgrade` in CI unless `AGORA_ALLOW_UPGRADE_IN_CI=1` is set; blocked runs return `status: "manual"` with `ciBlocked: true` and suggest `agora upgrade --check --json`.
+- Align `go.mod` module path with the public repository: `github.com/AgoraIO/cli` (replaces the workspace-only `github.com/agora/cli-workspace/agora-cli-go` path).
+- Rename GitHub release archives from `agora-cli-go_v*` to `agora-cli_v*` starting in v0.2.1 (install scripts and docs use the new name). `agora upgrade` selects the archive prefix from the target release version: `agora-cli-go_*` for v0.1.7–v0.2.0, `agora-cli_*` for v0.2.1+.
+
+### Fixed
+
+- Disable git credential helpers for quickstart clone subprocesses so `agora init` and `agora quickstart create` succeed in non-interactive agent and CI environments without macOS keychain access.
+- Pass `--` before the repo URL and target directory on `git clone` so values starting with `-` cannot be parsed as git options.
+- Fail fast with `QUICKSTART_GIT_MISSING` when `git` is not on `PATH`, with `QUICKSTART_REF_INVALID` for malformed `--ref` values, and with `QUICKSTART_REPO_OVERRIDE_INVALID` when the env override URL is malformed, instead of surfacing cryptic git errors.
+
+### Upgrade notes
+
+**Direct installer (`install.sh` / `install.ps1`):** Fresh installs and re-runs of the installer fetch the correct archive name automatically. If you are on v0.1.7 through v0.2.0 and `agora upgrade` fails to download v0.2.1+, re-run the installer once:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
+```
+
+Those older binaries only know the `agora-cli-go_*` archive prefix; after one reinstall, future upgrades use `agora-cli_*`.
+
+**npm / package managers:** Use your package manager as usual (`npm update -g agoraio-cli`, etc.). Archive naming does not affect npm installs.
+
+**Automation scripts:**
+
+| Before | After |
+| ------ | ----- |
+| `agora init demo --yes` (silent template pick) | `agora init demo --template nextjs --yes` (required) |
+| `agora upgrade` in CI jobs | `agora upgrade --check --json` (non-mutating) |
+| `agora open --target docs` in CI | URL-only by default; pass `--browser` to force launch |
+
+Set `AGORA_ALLOW_UPGRADE_IN_CI=1` only when a CI job intentionally needs to mutate the installed binary.
+
+### Documentation
+
+- Align `AGENTS.md` with shipped `project doctor --deep` behavior and document current `agora open` browser-launch rules.
+- Expand `docs/automation.md` and `docs/llms.txt` with MCP transport/auth caveats, headless CI guidance, init/upgrade automation fields, and `agora env-help` discovery pointers.
+- Update agent quickstart rule and skills examples to include deterministic init (`--new-project`) defaults.
+- Document MCP progress notifications (`_meta.progressToken`) in `docs/automation.md`, `docs/llms.txt`, `agora mcp serve` help, and the skills catalog.
+- Document envelope versioning policy, login NDJSON parsing, raw `project env` hints, and boolean config flag syntax (`--flag=false`) in automation and troubleshooting docs.
+- Surface enterprise install paths for locked-down environments in `README.md` and `docs/install.md`.
+- Fix contributor clone path in `CONTRIBUTING.md` to match the canonical `git clone … && cd cli/` layout.
+- Align npm package `repository.directory` paths with the repo root layout and update the issue template docs link.
+- Document archive naming and upgrade migration in `docs/install.md` and `docs/troubleshooting.md`.
+- Add a GitHub Pages skip link for keyboard navigation.
+
 ## [0.2.0] - 2026-05-05
 
 ### Added
@@ -199,7 +260,8 @@ Earlier entries pre-date this convention and only carry their version's compare
 - Support machine-readable JSON output for automation and agent workflows.
 - Ship automated release packaging through GoReleaser, including cross-platform archives, Linux packages, Homebrew, Scoop, npm wrapper packages, Docker images, and install scripts.
 
-[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/AgoraIO/cli/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/AgoraIO/cli/compare/v0.1.9...v0.2.0
 [0.1.9]: https://github.com/AgoraIO/cli/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/AgoraIO/cli/compare/v0.1.7...v0.1.8

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
 ```

README.md

@@ -51,6 +51,8 @@ npm install -g agoraio-cli
 irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 | iex
 ```
 
+Locked-down environments that block `curl | sh` can use npm, download a release archive from GitHub, or mirror the binary internally. Every release includes `checksums.txt`, a Cosign keyless signature, and an SBOM; see [docs/install.md](docs/install.md#enterprise--locked-down-environments) for manual tarball and verification steps.
+
 Notes:
 
 - The shell installer supports macOS, Linux, and Windows POSIX shells such as Git Bash. Use `install.ps1` for native PowerShell installs on Windows.
@@ -308,7 +310,7 @@ GitHub Actions are configured for:
 
 Release workflow behavior:
 
-- a pushed tag matching `v*` (for example `v0.2.0`) triggers the release workflow
+- a pushed tag matching `v*` (for example `v0.2.1`) triggers the release workflow
 - the workflow runs tests, builds release binaries, packages them, and publishes a GitHub release automatically
 - release artifacts include checksums
 

RELEASING.md

@@ -5,15 +5,15 @@ Releases are fully automated via GoReleaser. Pushing a `v*` tag is the only manu
 ## Release
 
 ```bash
-git tag v0.2.0
-git push origin v0.2.0
+git tag v0.2.1
+git push origin v0.2.1
 ```
 
 The release workflow (`.github/workflows/release.yml`) then:
 
 1. **GoReleaser** builds and publishes everything in parallel:
    - Cross-platform binaries (Linux, macOS, Windows — amd64 + arm64)
-   - Archives: `.tar.gz` (Unix), `.zip` (Windows)
+   - Archives: `agora-cli_v<version>_<os>_<arch>.{tar.gz,zip}` (v0.2.1+; older releases used `agora-cli-go_v*`)
    - Linux packages: `.deb`, `.rpm`, `.apk`
    - GitHub release with auto-generated changelog and checksums
    - Docker images → GitHub Container Registry (`ghcr.io/{owner}/agora-cli`)
@@ -33,6 +33,10 @@ The release workflow (`.github/workflows/release.yml`) then:
    - Rebuilds the signed apt repo on GitHub Pages
    - Requires `APT_SIGNING_KEY` secret + `APT_SIGNING_KEY_ID` variable
 
+## Release notes
+
+Before tagging, ensure [CHANGELOG.md](CHANGELOG.md) has the version section finalized, including any migration or upgrade notes. GoReleaser publishes auto-generated release notes from commits; paste highlights from the CHANGELOG section into the GitHub release description if you want a curated summary.
+
 ## Local Verification
 
 Before cutting a tag:

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() {

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">

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:

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;