docs: align README, AGENTS, CONTRIBUTING, and Pages entrypoints

Keep install commands on the GitHub raw installer across index and llms,
document open/mcp/completion and project metadata in README, refresh AGENTS
layout and release/tag notes, and match CONTRIBUTING to CHANGELOG [Unreleased]
plus docs-preview and automation cross-links.

Author: digitallysavvy

AGENTS.md

@@ -19,6 +19,8 @@ This repository contains Agora CLI, the native CLI for Agora developer onboardin
 
 ```
 main.go                     Entry point — wires the root command and calls Execute()
+cmd/
+  gendocs/                  Regenerates docs/commands.md from the live cobra tree
 internal/cli/
   app.go                    App struct, Execute(), output-mode resolver, env snapshot
   commands.go               Root command tree; subcommand builders for auth/config/upgrade/etc.
@@ -28,6 +30,11 @@ internal/cli/
   config.go                 appConfig type, defaults, env injection
   version.go                Build-time version vars, versionInfo, formattedVersion
   introspect.go             agora introspect + buildIntrospectionData (agent discovery contract)
+  mcp.go                    agora mcp serve — JSON-RPC MCP stdio transport + tool dispatch
+  open_targets.go           Canonical URLs for agora open (docs, Console, product docs)
+  features.go               Product feature catalog (rtc/rtm/convoai) shared by doctor, introspect, init defaults
+  cache.go                  Short-lived on-disk API caches (project list for shell completion)
+  completion.go             Dynamic shell completion helpers
   upgrade.go                agora upgrade self-update logic (download, SHA-256, atomic rename)
   progress.go               NDJSON progress event emitter for long-running JSON-mode commands
   auth.go                   login / logout / whoami / auth status
@@ -42,9 +49,15 @@ internal/cli/
 docs/
   automation.md             Stable JSON output contract — machine-consumption source of truth
   install.md                Direct installer, platform, CI, and security guidance
+  _config.yml               Jekyll / GitHub Pages configuration (human docs site)
+  _layouts/, assets/        Theme assets for Pages
+scripts/
+  preview-pages-site.sh      Local Jekyll build + URL injection (`make docs-preview`)
+  prepare-pages-site.py      Pages artifact prep (Markdown /md mirror, token expansion)
 .github/workflows/
   ci.yml                    Push/PR matrix: Ubuntu, macOS, Windows
   release.yml               Tag-driven cross-platform release
+  pages.yml                 Publish docs to GitHub Pages
   apt-repo.yml              Signed apt repository publishing
 ```
 
@@ -57,6 +70,8 @@ agora
 ├── init <name>                    Recommended path: reuses existing project (or creates if none); add --new-project to force creation
 ├── version                        Build version, commit, and date
 ├── introspect                     Machine-readable command metadata for agents
+├── open                           Open Console, CLI docs (human or /md/), or product docs
+├── mcp                            MCP stdio server for agent tool integrations
 ├── telemetry                      Telemetry status/enable/disable
 ├── upgrade (alias: update)        Print package-manager-specific upgrade guidance
 ├── project
@@ -181,7 +196,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.1.4` triggers the release workflow automatically.
+Tagging `v0.2.0` (or any `v*` semver tag) triggers the release workflow automatically.
 
 ## Gotchas
 

CONTRIBUTING.md

@@ -27,6 +27,7 @@ so it is kept current as the canonical engineering guide.
 For end-user behavior and machine-readable contracts, see:
 
 - [`README.md`](README.md) — install, getting-started, command tree.
+- [Published docs](https://agoraio.github.io/cli/) — human-readable CLI documentation (GitHub Pages).
 - [`docs/automation.md`](docs/automation.md) — JSON envelope, agent guidance,
   output mode precedence (including CI auto-detect).
 - [`docs/error-codes.md`](docs/error-codes.md) — every stable `error.code`.
@@ -66,8 +67,14 @@ gofmt -l .                                  # must print nothing
 golangci-lint run --timeout=5m              # uses .golangci.yml
 ./scripts/check-error-codes.sh              # docs/error-codes.md drift check
 go run ./cmd/gendocs -check                 # docs/commands.md drift check
+make docs-preview                           # optional: local Jekyll site + /md preview (requires Ruby/Jekyll)
 ```
 
+Documentation work:
+
+- Run `make docs-commands` after command-tree changes; CI uses `go run ./cmd/gendocs -check`.
+- For GitHub Pages content, use `make docs-preview` (see `scripts/preview-pages-site.sh`). Published docs resolve `@@CLI_DOCS_*@@` tokens via `scripts/prepare-pages-site.py` and `docs/site.env` as documented in `docs/automation.md`.
+
 Install `golangci-lint` (matches the CI version):
 
 ```bash
@@ -132,9 +139,11 @@ change; prefer adding a new code and deprecating the old one over a rename.
 
 - Fill in the [pull request template](.github/pull_request_template.md).
 - Make sure `make test && make lint` pass locally.
-- Include changelog entries in the `## Unreleased` section of `CHANGELOG.md`
+- Include changelog entries under the `## [Unreleased]` section of `CHANGELOG.md`
   for user-facing changes (new commands, behavior changes, breaking changes,
-  CLI exit code changes, error code additions).
+  CLI exit code changes, error code additions). When cutting a release, move
+  those bullets into a dated `## [x.y.z] - YYYY-MM-DD` section per the note at
+  the top of `CHANGELOG.md`.
 - For UI/UX-affecting changes (pretty output, prompts, progress events,
   errors), include before/after copy-paste samples in the PR description.
 

README.md

@@ -58,6 +58,7 @@ agora init my-nextjs-demo --template nextjs
 
 ## Docs
 
+- Human docs (GitHub Pages): [https://agoraio.github.io/cli/](https://agoraio.github.io/cli/)
 - 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)
@@ -79,6 +80,9 @@ The command model is intentionally layered:
 - `config` for local CLI defaults
 - `telemetry` for telemetry preferences
 - `upgrade` / `update` for package-manager-specific upgrade guidance
+- `open` to open the Console, published CLI docs (human or `/md/` Markdown), or product docs in a browser
+- `mcp` to run the CLI as a local MCP server (`agora mcp serve`) for agent integrations
+- `completion` for shell completion scripts (standard Cobra completion)
 
 Discover the full command tree:
 
@@ -125,6 +129,14 @@ Reads and updates local CLI defaults such as output mode, log level, and browser
 
 Reads and updates telemetry preferences. `DO_NOT_TRACK=1` disables telemetry at runtime.
 
+### `open`
+
+Opens curated URLs: Console (`--target console`), human CLI docs on GitHub Pages (`docs`), raw Markdown tree for agents (`docs-md`), and Agora product docs (`product-docs`). Use `--no-browser` to print the resolved URL.
+
+### `mcp`
+
+Runs the CLI as an MCP stdio server so MCP-capable clients can call Agora workflows as tools. Authenticate with `agora login` on the host first; OAuth is not exposed through MCP.
+
 ### `version`
 
 Prints build metadata. Release binaries include version, commit, and build date.
@@ -177,7 +189,7 @@ agora --help --all
 
 `quickstart env write` is different from `project env write`, but both keep dotenv files limited to runtime credentials.
 
-- `project env write` writes only `AGORA_APP_ID` and `AGORA_APP_CERTIFICATE`
+- `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
 
@@ -207,13 +219,15 @@ The `.agora/project.json` file is created or updated by:
 - `agora init`
 - `agora quickstart create ... --project ...`
 - `agora quickstart env write ...`
+- `agora project env write ...` (fills missing `projectType` / `envPath` when applicable)
 
 It stores durable non-secret metadata:
 
 - `projectId`
 - `projectName`
 - `region`
 - `template`
+- `projectType` (framework hint used for env layout when present)
 - `envPath`
 
 Examples:
@@ -265,7 +279,7 @@ GitHub Actions are configured for:
 
 Release workflow behavior:
 
-- a pushed tag like `v0.1.4` triggers the release workflow
+- a pushed tag matching `v*` (for example `v0.2.0`) triggers the release workflow
 - the workflow runs tests, builds release binaries, packages them, and publishes a GitHub release automatically
 - release artifacts include checksums
 

docs/index.md

@@ -17,7 +17,7 @@ title: Agora CLI Docs
       </svg>
       <span class="copy-text">Copy</span>
     </button>
-    <pre><code id="install-command">curl -fsSL https://download.agora.io/cli/install.sh | sh -s -- --add-to-path</code></pre>
+    <pre><code id="install-command">curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --add-to-path</code></pre>
   </div>
 </div>
 

docs/llms.txt

@@ -4,7 +4,7 @@
 
 ## Quick Start
 
-Install: curl -fsSL https://download.agora.io/cli/install.sh | sh
+Install: curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --add-to-path
 
 Login: agora login
 Initialize project: agora init my-demo --template nextjs