From 0aad7dcc7c382408ea1d2e8cda510f32e386c84d Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Fri, 5 Jun 2026 14:58:09 -0400
Subject: [PATCH 1/4] fix(quickstart): remove cloned template git history

---
 AGENTS.md                                   |  2 +-
 CHANGELOG.md                                |  4 ++++
 docs/automation.md                          |  2 ++
 internal/cli/integration_quickstart_test.go |  7 +++++--
 internal/cli/quickstart.go                  | 13 +++++++++++-
 internal/cli/quickstart_test.go             | 22 +++++++++++++++++++++
 6 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index a5d1c38..40b265a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -104,7 +104,7 @@ agora
 
 **Design rules — do not break these:**
 - `project` = remote Agora control-plane resource; it never scaffolds local files
-- `quickstart` = local repo clone; requires `git` on the PATH
+- `quickstart` = local repo clone; requires `git` on the PATH; upstream `.git` is removed after clone so demos start without template history
 - `init` = the only command that composes both
 - The `add` namespace is reserved; keep it hidden and return a command-not-found error if invoked
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 51e344c..01830c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,10 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [Unreleased]
 
+### Changed
+
+- Remove upstream `.git` metadata after quickstart scaffolds are cloned so demos start without the template repository's history.
+
 ## [0.2.5] - 2026-06-01
 
 Installer migration improvements.
diff --git a/docs/automation.md b/docs/automation.md
index 4488908..5e23ac2 100644
--- a/docs/automation.md
+++ b/docs/automation.md
@@ -214,6 +214,7 @@ Additional stage-specific fields may appear (for example `repoUrl`, `projectId`,
 | `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` |
+| `clone:strip-git` | `quickstart create`, `init` | After upstream `.git` metadata is removed from the scaffold | `targetPath` |
 | `project:create` | `init` | Before creating a new Agora project | `projectName`, `features` |
 | `project:created` | `init` | After the project is ready | `projectId`, `projectName` |
 | `project:reuse` | `init` | When binding to an existing project | `projectId`, `projectName` |
@@ -227,6 +228,7 @@ Additional stage-specific fields may appear (for example `repoUrl`, `projectId`,
 {"event":"progress","command":"init","stage":"project:reuse","message":"Reusing existing Agora project","timestamp":"...","projectId":"prj_abc","projectName":"Default Project"}
 {"event":"progress","command":"init","stage":"clone:start","message":"Cloning quickstart repository","timestamp":"...","repoUrl":"...","targetPath":"...","ref":""}
 {"event":"progress","command":"init","stage":"clone:complete","message":"Quickstart repository cloned","timestamp":"...","targetPath":"..."}
+{"event":"progress","command":"init","stage":"clone:strip-git","message":"Removed quickstart repository history","timestamp":"...","targetPath":"..."}
 {"ok":true,"command":"init","data":{},"meta":{"exitCode":0,"outputMode":"json"}}
 ```
 
diff --git a/internal/cli/integration_quickstart_test.go b/internal/cli/integration_quickstart_test.go
index 96dc52b..1c8e8f2 100644
--- a/internal/cli/integration_quickstart_test.go
+++ b/internal/cli/integration_quickstart_test.go
@@ -74,8 +74,11 @@ func TestCLIQuickstartListAndCreate(t *testing.T) {
 	if createUnbound.exitCode != 0 || !strings.Contains(createUnbound.stdout, `"envStatus":"template-only"`) {
 		t.Fatalf("unexpected unbound quickstart create result: %+v", createUnbound)
 	}
-	if _, err := os.Stat(filepath.Join(unboundTarget, ".git")); err != nil {
-		t.Fatalf("expected cloned git repo in unbound scaffold: %v", err)
+	if !strings.Contains(createUnbound.stdout, `"written":[]`) {
+		t.Fatalf("expected unbound quickstart written field to be an empty array, got: %s", createUnbound.stdout)
+	}
+	if _, err := os.Stat(filepath.Join(unboundTarget, ".git")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("did not expect upstream .git in unbound scaffold, got %v", err)
 	}
 	if _, err := os.Stat(filepath.Join(unboundTarget, ".env.local")); !errors.Is(err, os.ErrNotExist) {
 		t.Fatalf("did not expect .env.local in unbound scaffold, got %v", err)
diff --git a/internal/cli/quickstart.go b/internal/cli/quickstart.go
index 1becb5e..222e990 100644
--- a/internal/cli/quickstart.go
+++ b/internal/cli/quickstart.go
@@ -300,8 +300,15 @@ func (a *App) quickstartCreate(template quickstartTemplate, targetDir, explicitP
 		return nil, err
 	}
 	progress.emit("clone:complete", "Quickstart repository cloned", map[string]any{"targetPath": absTarget})
+	if err := stripClonedGitMetadata(absTarget); err != nil {
+		if cleanupErr := os.RemoveAll(absTarget); cleanupErr != nil {
+			return nil, fmt.Errorf("failed to remove quickstart git metadata after clone: %v; cleanup also failed for %s: %v", err, absTarget, cleanupErr)
+		}
+		return nil, fmt.Errorf("failed to remove quickstart git metadata after clone: %v; removed %s", err, absTarget)
+	}
+	progress.emit("clone:strip-git", "Removed quickstart repository history", map[string]any{"targetPath": absTarget})
 
-	written := []string{".git"}
+	written := []string{}
 	envStatus := "template-only"
 	envPath := ""
 	if boundProject != nil {
@@ -432,6 +439,10 @@ func (a *App) quickstartRepoURL(template quickstartTemplate) (string, string, er
 	return template.RepoURL, "", nil
 }
 
+func stripClonedGitMetadata(targetDir string) error {
+	return os.RemoveAll(filepath.Join(targetDir, ".git"))
+}
+
 func cloneQuickstartRepo(repoURL, targetDir, ref string) error {
 	if err := validateGitRef(ref); err != nil {
 		return &cliError{
diff --git a/internal/cli/quickstart_test.go b/internal/cli/quickstart_test.go
index a4a82fa..9be94f2 100644
--- a/internal/cli/quickstart_test.go
+++ b/internal/cli/quickstart_test.go
@@ -28,6 +28,28 @@ func TestGitQuickstartCloneArgs(t *testing.T) {
 	}
 }
 
+func TestStripClonedGitMetadata(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 before strip: %v", err)
+	}
+	if err := stripClonedGitMetadata(target); err != nil {
+		t.Fatalf("stripClonedGitMetadata failed: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(target, ".git")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("expected .git removed after strip, got %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(target, "README.md")); err != nil {
+		t.Fatalf("expected README to remain after strip: %v", err)
+	}
+}
+
 func TestCloneQuickstartRepoLocal(t *testing.T) {
 	repo := createLocalGitRepo(t, map[string]string{
 		"README.md": "# Quickstart\n",

From 3e435fe653cde14ac651ec38df8e7d68c556d23a Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Fri, 5 Jun 2026 14:58:33 -0400
Subject: [PATCH 2/4] docs: refresh onboarding and contributor guidance

---
 CONTRIBUTING.md |  16 ++++
 README.md       | 240 ++++++++++++++++++++++--------------------------
 2 files changed, 124 insertions(+), 132 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c693a37..84a984f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -128,6 +128,22 @@ change; prefer adding a new code and deprecating the old one over a rename.
   that is part of the public contract (JSON shape, exit code, stderr text).
   Use `app_test.go` for isolated helper logic.
 
+## CI and releases
+
+GitHub Actions are configured for:
+
+- push and pull request validation on Linux, macOS, and Windows
+- automated tag-driven releases for `v*` tags
+- cross-platform release artifacts for Linux, macOS, and Windows
+
+Release workflow behavior:
+
+- a pushed tag matching `v*` (for example `v0.2.5`) triggers the release workflow
+- the workflow runs tests, builds release binaries, packages them, and publishes a GitHub release automatically
+- release artifacts include checksums, Cosign signatures, and an SBOM
+
+See [AGENTS.md](AGENTS.md) for the full release pipeline (npm, Homebrew, apt, GitHub Pages).
+
 ## Branching model
 
 - `main` is always releasable. CI must be green before merge.
diff --git a/README.md b/README.md
index 457dcc6..d4e6067 100644
--- a/README.md
+++ b/README.md
@@ -7,19 +7,6 @@
 
 Native Agora CLI for authentication, project management, quickstart setup, and developer onboarding. Use it to go from an Agora account to a runnable app with one command.
 
-```bash
-agora login
-agora init my-nextjs-demo --template nextjs
-```
-
-## What You Can Build Quickly
-
-| Goal | Command | What You Get |
-|------|---------|--------------|
-| Next.js video app | `agora init my-nextjs-demo --template nextjs` | A cloned Next.js quickstart, project binding, and `.env.local` |
-| Python voice agent | `agora init my-python-demo --template python` | A Python quickstart with Agora credentials written for the backend |
-| Go token service | `agora init my-go-demo --template go` | A Go server quickstart with project metadata and env wiring |
-
 ## Install
 
 ### Requirements
@@ -51,7 +38,7 @@ 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.
+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, checksum, and Cosign verification steps.
 
 Notes:
 
@@ -59,51 +46,44 @@ Notes:
 - **Shell setup is auto-on**: the installer wires the install directory onto your `PATH` (when needed) and writes a shell completion script for the detected shell (bash, zsh, fish, or PowerShell). Pass `--no-path`, `--no-completion`, or the umbrella `--skip-shell` (PowerShell: `-NoPath` / `-NoCompletion` / `-SkipShell`) to opt out granularly.
 - Installer help is always available with `curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --help`.
 - Pinned versions, dry runs, custom install directories, npm details, and source builds are documented in [docs/install.md](docs/install.md).
+- Release artifacts and checksums: [GitHub Releases](https://github.com/AgoraIO/cli/releases). Vulnerability disclosures: [SECURITY.md](SECURITY.md).
 
-### Verifying release artifacts
-
-Every release ships with a SHA-256 `checksums.txt` and a Cosign keyless signature. The official installers verify the SHA-256 automatically. You can also verify manually:
+### Build from source
 
 ```bash
-# Verify SHA-256 against the published checksums.txt
-curl -fsSLO https://github.com/AgoraIO/cli/releases/download/vX.Y.Z/checksums.txt
-sha256sum -c checksums.txt --ignore-missing
+go build -o agora .
+./agora --help
 ```
 
-For Cosign signature verification and the SBOM workflow, see the **Security** section of [docs/install.md](docs/install.md). Vulnerability disclosures: see [SECURITY.md](SECURITY.md).
+Requires the Go toolchain pinned in [go.mod](go.mod). For direct installer options and source install notes, see [docs/install.md](docs/install.md).
 
-## First Run
+## Quick Start
 
 ```bash
 agora login
 agora init my-nextjs-demo --template nextjs
+agora project doctor --json
 ```
 
-## Docs
+Command examples use `agora` for the installed CLI. Local source builds use `./agora` from the repo root.
 
-- Human docs (GitHub Pages): [https://agoraio.github.io/cli/](https://agoraio.github.io/cli/)
-- Agent-friendly Markdown mirror: [https://agoraio.github.io/cli/md/](https://agoraio.github.io/cli/md/)
-- Release notes: [CHANGELOG.md](CHANGELOG.md)
-- Install options (direct installer, Windows, source): [docs/install.md](docs/install.md)
-- Full command reference (auto-generated): [docs/commands.md](docs/commands.md)
-- Automation and JSON contract: [docs/automation.md](docs/automation.md)
-- JSON envelope schema (machine-readable): [docs/schema/envelope.v1.json](docs/schema/envelope.v1.json)
-- Stable error codes: [docs/error-codes.md](docs/error-codes.md)
-- Telemetry controls: [docs/telemetry.md](docs/telemetry.md)
-- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
-- Security policy: [SECURITY.md](SECURITY.md)
-- Support and contact channels: [SUPPORT.md](SUPPORT.md)
-- Contributor and agent guide: [AGENTS.md](AGENTS.md), plus [CONTRIBUTING.md](CONTRIBUTING.md)
+## What You Can Build Quickly
 
-Command examples use `agora` for the installed CLI. Local source builds are covered in [Build From Source](#build-from-source).
+| Goal | Command | What You Get |
+|------|---------|--------------|
+| Next.js video app | `agora init my-nextjs-demo --template nextjs` | A cloned Next.js quickstart, project binding, and `.env.local` |
+| Python voice agent | `agora init my-python-demo --template python` | A Python quickstart with Agora credentials written for the backend |
+| Go token service | `agora init my-go-demo --template go` | A Go server quickstart with project metadata and env wiring |
+
+Run `agora quickstart list` to see all available templates.
 
 ## Command Model
 
 The command model is intentionally layered:
 
-- `init` for the recommended onboarding path
-- `quickstart` for standalone starter repos
-- `project` for remote Agora resources and env export
+- `init` for the recommended onboarding path (project + clone + env)
+- `quickstart` for local cloned starter repos (requires `git`)
+- `project` for remote Agora control-plane resources (does not clone scaffolds)
 - `auth` for login and session inspection
 - `config` for local CLI defaults
 - `telemetry` for telemetry preferences
@@ -115,6 +95,29 @@ The command model is intentionally layered:
 - `mcp` to run the CLI as a local MCP server (`agora mcp serve`) for agent integrations
 - `completion` for shell completion scripts (auto-installed by the installer; see `agora completion --help` for manual setup)
 
+### Which command?
+
+| Goal | Command |
+|------|---------|
+| New user, one shot | `agora init <name> --template <id>` |
+| List available templates | `agora quickstart list` |
+| Clone a starter only | `agora quickstart create ...` |
+| Re-sync env in a cloned quickstart | `agora quickstart env write [dir]` |
+| Write env to an arbitrary path / non-quickstart repo | `agora project env write <path>` |
+| Install self-test | `agora doctor --json` |
+| Project/workspace readiness | `agora project doctor --json` |
+
+### Env-related commands
+
+```
+agora init <name>                    # recommended: project + clone + env
+├── project
+│   ├── env                          Print project env values (no file write)
+│   └── env write <path>             Generic dotenv block (AGORA_* or NEXT_*)
+└── quickstart
+    └── env write [dir]              Template-specific env file and key names
+```
+
 Discover the full command tree:
 
 ```bash
@@ -133,6 +136,7 @@ Manages standalone official starter repos and their runtime-specific env files.
 
 Use this when you want to:
 
+- list available templates with `quickstart list`
 - clone a quickstart without creating a project
 - bind a quickstart to an existing project
 - re-sync env files after changing project selection
@@ -145,7 +149,8 @@ Use this when you want to:
 
 - create or inspect projects directly
 - switch the default project context
-- export project env values
+- export project env values with `project env`
+- write credentials to a dotenv file with `project env write`
 - inspect project readiness with `project doctor`
 
 ### `auth`
@@ -172,72 +177,30 @@ Runs the CLI as a local MCP server so MCP-capable clients can call Agora workflo
 
 Prints build metadata. Release binaries include version, commit, and build date.
 
-## Common Workflows
-
-### Onboard a new demo
-
-```bash
-agora login
-agora init my-nextjs-demo --template nextjs
-```
-
-### Use an existing project with a quickstart
-
-```bash
-agora quickstart create my-go-demo --template go --project my-existing-project
-agora quickstart env write my-go-demo --project my-existing-project
-```
-
-### Update env after changing projects
-
-```bash
-agora project use my-agent-demo
-agora quickstart env write my-go-demo
-```
-
-### Inspect project readiness
-
-```bash
-agora project doctor
-agora project doctor --json
-```
-
-### Use low-level commands directly
-
-```bash
-agora project create my-agent-demo --feature rtc --feature convoai
-agora quickstart create my-go-demo --template go --project my-agent-demo
-agora quickstart env write my-go-demo --project my-agent-demo
-```
-
-### Inspect the full command tree
-
-```bash
-agora --help --all
-```
+## Env Files and Project Binding
 
-## Quickstart Env Conventions
+`quickstart env write` and `project env write` both keep dotenv files limited to runtime credentials, but they target different workflows:
 
-`quickstart env write` is different from `project env write`, but both keep dotenv files limited to runtime credentials.
+| Command | Env path | Key names |
+|---------|----------|-----------|
+| `agora init` / `quickstart env write` | Template-defined (`.env.local`, `server/.env`, etc.) | Template-specific (`NEXT_PUBLIC_*`, `APP_ID`, …) |
+| `agora project env write <path>` | User-supplied path | `AGORA_*` or `NEXT_*` only |
 
-- `project env write` writes only App ID and App Certificate keys for the detected or `--template`-selected layout (for example `AGORA_*` for standard Node, `NEXT_PUBLIC_*` / `NEXT_*` for Next.js, or `APP_ID` / `APP_CERTIFICATE` for Python and Go). See [docs/automation.md](docs/automation.md) for the full matrix and JSON fields.
-- `quickstart env write` understands the quickstart type and writes only the App ID and App Certificate variable names the cloned repo expects
-- existing `.env` and `.env.local` files are preserved; the CLI appends missing credentials, updates existing credential keys, and comments out duplicate or stale Agora credential aliases for the selected runtime
+Quickstart template behavior:
 
-Template-specific behavior:
-
-- Generic project env writes use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE`
-- Next.js quickstarts write `.env.local` and use `NEXT_PUBLIC_AGORA_APP_ID` plus `NEXT_AGORA_APP_CERTIFICATE`
+- Next.js quickstarts write `.env.local` with `NEXT_PUBLIC_AGORA_APP_ID` plus `NEXT_AGORA_APP_CERTIFICATE`
 - Python quickstarts copy `server/env.example` to `server/.env`, then use `APP_ID` plus `APP_CERTIFICATE`
 - Go quickstarts copy `server-go/env.example` to `server-go/.env`, then use `APP_ID` plus `APP_CERTIFICATE`
 
-The CLI also writes repo-local project metadata to:
+`project env write` auto-detects Next.js workspaces (or accepts `--template nextjs|standard`) and writes `AGORA_APP_ID` / `AGORA_APP_CERTIFICATE` or the Next.js equivalents. It does not use `APP_ID` / `APP_CERTIFICATE`; use `quickstart env write` for Python and Go quickstart layouts.
+
+Existing `.env` and `.env.local` files are preserved: the CLI appends missing credentials, updates existing credential keys, and comments out duplicate or stale Agora credential aliases for the selected runtime.
 
-- `.agora/project.json`
+See [docs/automation.md](docs/automation.md) for JSON fields and the full credential matrix.
 
-That allows the CLI to detect which Agora project a cloned demo is bound to even when you are working inside the repo later.
+### Repo-local binding
 
-## Repo-Local Project Binding
+The CLI writes repo-local project metadata to `.agora/project.json` so it can detect which Agora project a cloned demo is bound to even when you work inside the repo later.
 
 Project resolution precedence is consistent across commands:
 
@@ -274,20 +237,40 @@ agora quickstart env write /abs/path/to/my-go-demo --json
 agora quickstart env write /abs/path/to/my-go-demo --project my-other-project --json
 ```
 
-## Automation / Agent Usage
+## Common Workflows
+
+### Use an existing project with a quickstart
+
+```bash
+agora quickstart create my-go-demo --template go --project my-existing-project
+agora quickstart env write my-go-demo --project my-existing-project
+```
+
+### Update env after changing projects
+
+```bash
+agora project use my-agent-demo
+agora quickstart env write my-go-demo
+```
+
+### Use low-level commands directly
+
+```bash
+agora project create my-agent-demo --feature rtc --feature convoai
+agora quickstart create my-go-demo --template go --project my-agent-demo
+agora quickstart env write my-go-demo --project my-agent-demo
+```
+
+## Automation and Agents
 
 For scripts, CI, and agentic workflows:
 
 - prefer `--json` for machine consumption
 - set `AGORA_HOME` to an isolated temporary directory in CI or multi-agent runs
-- prefer `init` for end-to-end setup
-- use low-level commands when the workflow must be decomposed or resumed in stages
-- use `agora --help --all` to inspect the full command tree
-- use `quickstart env write` to re-sync env files after changing project selection
-- use `project doctor --json` for readiness checks
-- rely on the same JSON envelope for both success and failure
+- prefer `init` for end-to-end setup; decompose with lower-level commands when a workflow must be resumed in stages
+- use `agora introspect --json` and [AGENTS.md](AGENTS.md) for agent discovery; [docs/automation.md](docs/automation.md) for the JSON envelope contract
 
-Examples:
+Example:
 
 ```bash
 export AGORA_HOME="$(mktemp -d)"
@@ -298,21 +281,7 @@ agora project doctor --json
 agora auth status --json
 ```
 
-The JSON envelope and stable result shapes are documented in [docs/automation.md](docs/automation.md). `auth status --json` exits `3` with `error.code` set to `AUTH_UNAUTHENTICATED` when no local session exists.
-
-## CI and Releases
-
-GitHub Actions are configured for:
-
-- push and pull request validation on Linux, macOS, and Windows
-- automated tag-driven releases for `v*` tags
-- cross-platform release artifacts for Linux, macOS, and Windows
-
-Release workflow behavior:
-
-- a pushed tag matching `v*` (for example `v0.2.5`) triggers the release workflow
-- the workflow runs tests, builds release binaries, packages them, and publishes a GitHub release automatically
-- release artifacts include checksums
+`auth status --json` exits `3` with `error.code` set to `AUTH_UNAUTHENTICATED` when no local session exists.
 
 ## Configuration
 
@@ -329,12 +298,12 @@ Built-in default config values are documented in [config.example.json](config.ex
 
 ## Troubleshooting
 
-For a full troubleshooting guide with diagnostic commands, see [docs/troubleshooting.md](docs/troubleshooting.md). The fastest first step is always:
+For a full troubleshooting guide with diagnostic commands, see [docs/troubleshooting.md](docs/troubleshooting.md).
 
-```bash
-agora doctor --json
-agora project doctor --json
-```
+Start with the right doctor command:
+
+- **`agora doctor --json`** — install self-test (PATH, version, network, auth, MCP host)
+- **`agora project doctor --json`** — project and workspace readiness (credentials, `.agora` binding, env consistency; add `--deep` for repo-local checks)
 
 The most common issues:
 
@@ -346,11 +315,18 @@ The most common issues:
 
 Full guide with debug logging, CI tips, completion troubleshooting, and the `--debug` flag: [docs/troubleshooting.md](docs/troubleshooting.md).
 
-## Build From Source
-
-```bash
-go build -o agora .
-./agora --help
-```
+## Documentation
 
-Requires the Go toolchain pinned in [go.mod](go.mod). For direct installer options and source install notes, see [docs/install.md](docs/install.md).
+- Human docs (GitHub Pages): [https://agoraio.github.io/cli/](https://agoraio.github.io/cli/)
+- Agent-friendly Markdown mirror: [https://agoraio.github.io/cli/md/](https://agoraio.github.io/cli/md/)
+- Release notes: [CHANGELOG.md](CHANGELOG.md)
+- Install options (direct installer, Windows, source): [docs/install.md](docs/install.md)
+- Full command reference (auto-generated): [docs/commands.md](docs/commands.md)
+- Automation and JSON contract: [docs/automation.md](docs/automation.md)
+- JSON envelope schema (machine-readable): [docs/schema/envelope.v1.json](docs/schema/envelope.v1.json)
+- Stable error codes: [docs/error-codes.md](docs/error-codes.md)
+- Telemetry controls: [docs/telemetry.md](docs/telemetry.md)
+- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
+- Security policy: [SECURITY.md](SECURITY.md)
+- Support and contact channels: [SUPPORT.md](SUPPORT.md)
+- Contributor and agent guide: [AGENTS.md](AGENTS.md), plus [CONTRIBUTING.md](CONTRIBUTING.md)

From f15505529c54dc9b337907e16a359997dabe34c4 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Fri, 5 Jun 2026 15:06:27 -0400
Subject: [PATCH 3/4] docs(release): prepare v0.2.5 notes

Finalize the v0.2.5 changelog and refresh install doc examples. Clarify that GitHub tokens are optional and only needed when latest-release API lookups hit rate limits; pinning VERSION skips that lookup entirely.
---
 .github/ISSUE_TEMPLATE/bug_report.yml |  2 +-
 CHANGELOG.md                          | 12 ++++++------
 RELEASING.md                          |  2 +-
 docs/install.md                       | 25 ++++++++++++++++---------
 docs/llms.txt                         |  2 +-
 5 files changed, 25 insertions(+), 18 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index a5b5df3..00d1f0c 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.2 (commit abc1234, built 2026-05-26)"
+      placeholder: "e.g. agora-cli 0.2.5 (commit abc1234, built 2026-06-05)"
     validations:
       required: true
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 01830c6..24e6c76 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,22 +15,22 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [Unreleased]
 
-### Changed
-
-- Remove upstream `.git` metadata after quickstart scaffolds are cloned so demos start without the template repository's history.
+## [0.2.5] - 2026-06-05
 
-## [0.2.5] - 2026-06-01
-
-Installer migration improvements.
+Installer migration, quickstart scaffold cleanup, and onboarding doc refresh.
 
 ### Added
 
 - Add `install.sh --replace-npm` to migrate from a global npm-managed `agoraio-cli` install to the standalone installer by running `npm uninstall -g agoraio-cli` before installing the binary.
+- Emit a `clone:strip-git` progress event after removing upstream template git metadata during quickstart scaffolds.
 
 ### Changed
 
+- Remove upstream `.git` metadata after quickstart scaffolds are cloned so demos start without the template repository's history.
 - Improve managed-install errors with explicit uninstall-and-reinstall guidance so users can switch to the standalone installer without relying on side-by-side PATH shadowing.
 - Update website install and troubleshooting docs with npm-to-standalone migration steps and clearer PATH shadowing guidance.
+- Restructure README quick start, command routing tables, env workflows, and documentation index.
+- Document CI and release workflow expectations in CONTRIBUTING.md.
 
 ## [0.2.4] - 2026-06-01
 
diff --git a/RELEASING.md b/RELEASING.md
index 42b5c7a..6db0567 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, 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.
+Before tagging, ensure [CHANGELOG.md](CHANGELOG.md) has the version section finalized (empty `[Unreleased]`, dated release heading, updated compare links), 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/install.md b/docs/install.md
index 2ef9cf0..60ff716 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -38,7 +38,7 @@ agora --help
 Install a pinned version:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --version 0.2.1
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --version 0.2.5
 agora --help
 ```
 
@@ -80,7 +80,7 @@ agora --help
 Install a pinned version:
 
 ```powershell
-$env:VERSION = "0.2.1"
+$env:VERSION = "0.2.5"
 irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 | iex
 agora --help
 ```
@@ -162,7 +162,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.1` and `v0.2.1` are accepted.
+- `VERSION`: install a specific version. Both `0.2.5` and `v0.2.5` 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.
 
@@ -272,7 +272,7 @@ agora --help
 npx agoraio-cli --help
 
 # Pin a specific version
-npm install -g agoraio-cli@0.2.1
+npm install -g agoraio-cli@0.2.5
 
 # Update to the latest published version
 npm update -g agoraio-cli
@@ -297,15 +297,22 @@ For one-off shell sessions, source the generated script according to your shell'
 
 ### GitHub API rate limits
 
-If latest-version resolution fails, retry with a pinned version or provide `GITHUB_TOKEN` / `GH_TOKEN`:
+The direct installers call the GitHub REST API only when resolving the latest release. The binary download itself uses public release URLs and does not require authentication.
+
+If latest-version resolution fails, pin `VERSION` first — that skips the API lookup entirely:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --version 0.2.5
+```
+
+If you must resolve latest from a shared IP (for example CI) and hit GitHub's unauthenticated API rate limit, optionally provide `GITHUB_TOKEN` or `GH_TOKEN`:
 
 ```bash
-GITHUB_TOKEN=your-token-here VERSION=0.2.1 sh install.sh
+GITHUB_TOKEN=your-token-here sh install.sh
 ```
 
 ```powershell
 $env:GITHUB_TOKEN = "your-token-here"
-$env:VERSION = "0.2.1"
 & ([scriptblock]::Create((irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1)))
 ```
 
@@ -380,8 +387,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.1_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.5_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.1_linux_amd64.tar.gz.spdx.json
+grype sbom:agora-cli_v0.2.5_linux_amd64.tar.gz.spdx.json
 ```
diff --git a/docs/llms.txt b/docs/llms.txt
index d875887..12a70f9 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -39,7 +39,7 @@ Check project health: agora project doctor --json
 - **Project Management**: Initialize, configure, and validate Agora projects
 - **JSON Output**: All commands support --json for automation and scripting (see Automation Notes below for one documented exception)
 - **Stable Exit Codes**: Consistent error codes for CI/CD integration
-- **Template System**: Quick-start templates for Next.js, Python, and Go (see `agora init --help` for the current catalog)
+- **Template System**: Quick-start templates for Next.js, Python, and Go (see `agora init --help` for the current catalog). Quickstart clones drop upstream `.git` metadata so scaffolds start as clean local repos.
 - **Cross-Platform**: macOS, Linux, Windows support
 - **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

From 9542b456f935cd4b1ead6282c3938db24da0f575 Mon Sep 17 00:00:00 2001
From: digitallysavvy <hermes.frangoudis@gmail.com>
Date: Fri, 5 Jun 2026 15:12:33 -0400
Subject: [PATCH 4/4] fix(build): bump Go toolchain to 1.26.4

Resolve govulncheck failures for GO-2026-5037 and GO-2026-5039 by rebuilding on the patched stdlib release.
---
 CHANGELOG.md | 4 ++++
 go.mod       | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 24e6c76..65194ac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,10 @@ Installer migration, quickstart scaffold cleanup, and onboarding doc refresh.
 - Restructure README quick start, command routing tables, env workflows, and documentation index.
 - Document CI and release workflow expectations in CONTRIBUTING.md.
 
+### Fixed
+
+- Bump the pinned Go toolchain to 1.26.4 so release builds include stdlib fixes for GO-2026-5037 and GO-2026-5039.
+
 ## [0.2.4] - 2026-06-01
 
 npm release workflow trigger tag for the v0.2.3 Cosign bundle signing fix.
diff --git a/go.mod b/go.mod
index f5b3b76..285a358 100644
--- a/go.mod
+++ b/go.mod
@@ -1,6 +1,6 @@
 module github.com/AgoraIO/cli
 
-go 1.26.3
+go 1.26.4
 
 require (
 	github.com/spf13/cobra v1.10.2