dsh-agora 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dsh-agora contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# dsh-agora
+
+DSH (DeepSeek Harness) skill plugin: a **thin shell** that ships the Agora
+skill — RTC, RTM, ConvoAI, CLI, Cloud Recording, Server, Server Gateway,
+tokens — synced **verbatim** from
+[`AgoraIO/skills`](https://github.com/AgoraIO/skills) at a pinned release tag.
+
+The plugin registers one bundled skill, `agora`, into DSH's skill registry —
+the same name and content as the Claude Code / Cursor ecosystems.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-agora
+```
+
+Then restart the web profile. The `agora` skill appears in the skill catalog.
+
+From a local checkout (development):
+
+```sh
+dsh plugin --profile web add /path/to/dsh-agora
+```
+
+> **pnpm workspace-root gotcha**: with pnpm ≥ 8.15 the profile's workspace
+> root rejects a bare `add` (`ERR_PNPM_ADDING_TO_ROOT`). Add `-w`:
+> `dsh plugin --profile web add -w <pkg>`.
+>
+> **link: dev mode**: the profile must resolve the runtime peer
+> `@deepseek-ai/dsh-skill`. Install it in the repo checkout first
+> (`pnpm install`); otherwise `index.js` fails with
+> `ERR_MODULE_NOT_FOUND` at load time (decision D-09).
+
+## What it contains
+
+```
+dsh-agora/
+├── package.json            # dsh.bundle.patch declaration (bundle form)
+├── cordis.patch.yml        # inserts the provider row into the profile tree
+├── index.js                # Cordis entry: registers the bundled agora provider
+├── scripts/sync-deps.sh    # ★ the only automation: tag-sync from AgoraIO/skills
+└── assets/agora/           # synced output (gitignored, not committed)
+    ├── SKILL.md            # upstream verbatim, zero rewrite
+    └── references/         # full reference set (54 files)
+```
+
+## How content stays in sync
+
+`npm publish` runs `prepack` → `scripts/sync-deps.sh`, which:
+
+1. resolves the release tag (`$TAG` env → GitHub latest release → pinned
+   fallback `v1.8.1`),
+2. pulls the `AgoraIO/skills` tarball for that tag,
+3. `rsync -a --delete`s `skills/agora/` → `assets/agora/` — **zero rewrite**,
+   so the two copies can never drift.
+
+The repo keeps no permanent copy of the skill content; `assets/` is
+gitignored and rebuilt at release time. Run it manually with
+`npm run sync:deps`.
+
+## Skill: `agora`
+
+Upstream routing: RTC (video/voice calls), RTM (chat/signaling), ConvoAI
+(voice AI agents), Agora CLI, Cloud Recording, Server (tokens), Server
+Gateway, and cross-product coordination. ConvoAI follows the upstream
+"proven baseline first" rule (run the official quickstart before scaffolding
+from memory); CLI acceleration is runtime-detected (`agora` on `PATH`), never
+bundled.
+
+Design rules and decisions (D-01…D-10) and the ROADMAP are kept local-only
+under `docs/` — not committed to this public repo.
+
+## Verify locally
+
+```sh
+dsh --profile web --dump-config --patch ./cordis.patch.yml   # row composes
+```
+
+For a real mount test, install into a throwaway profile:
+
+```sh
+dsh plugin --profile agoratest add .
+dsh --profile agoratest --dump-config | grep agora-skills
+```
+
+## License
+
+MIT

package/assets/agora/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: agora
+description: >-
+  Activate when the user wants to build voice AI agents, video or voice calls,
+  live streaming, screen sharing, in-app messaging and presence, recording,
+  token or auth flows, or use the `agora` CLI for login, quickstarts, env
+  setup, diagnostics, introspection, skills, or MCP serving, especially when
+  integrating Agora into an app.
+metadata:
+  author: agora
+  version: '1.8.1'
+---
+
+<!-- applies-from: v0.2.1 -->
+
+# Agora (agora.io)
+
+Top-level workflow for selecting the right Agora path and loading only the references needed for the task.
+
+## Workflow
+
+1. Identify the user's primary goal from the problem they are solving.
+2. Choose exactly one primary route first: RTC, RTM, ConvoAI, CLI, Cloud Recording, Server, Server Gateway, or Cross-product coordination.
+3. Load only the primary product README first.
+4. When the ConvoAI route is chosen and read-only workspace detection finds outdated server SDK package or module names — or the user asks to migrate — load **[references/conversational-ai/server-sdk-rename.md](references/conversational-ai/server-sdk-rename.md)** before editing manifests or imports. Do not load it for greenfield ConvoAI work.
+5. If the task clearly spans multiple products, add the minimum supporting references after the primary route is chosen.
+6. If the request matches ConvoAI and there is no proven working baseline yet, stop and follow the quickstart path before generating custom code from memory or scaffolding a replacement app.
+7. Ask one short clarification only if the route is still ambiguous after checking the obvious cues below.
+8. Use Level 2 documentation lookup only when the local references do not cover the needed detail.
+
+## Route Selection
+
+- **RTC**: video calls, voice chat, livestream, screen share, join/publish/subscribe tracks
+  Route to **[references/rtc/README.md](references/rtc/README.md)**.
+- **RTM**: chat, signaling, presence, metadata, notifications inside the client
+  Route to **[references/rtm/README.md](references/rtm/README.md)**.
+- **ConvoAI**: AI assistant, voice bot, agent demo, provider choice, MLLM, Studio Agent ID, agent backend
+  Route to **[references/conversational-ai/README.md](references/conversational-ai/README.md)**.
+- **ConvoAI + existing app**: user already has a codebase and wants ConvoAI added
+  Route to **[references/conversational-ai/README.md](references/conversational-ai/README.md)** first, then **[references/conversational-ai/integration-from-quickstart.md](references/conversational-ai/integration-from-quickstart.md)** after the official quickstart has been cloned and inspected.
+- **Agora CLI**: `agora` install, login, project selection, `init`, `quickstart`, env export, quickstart env binding, feature enablement, `doctor`, `project doctor`, env help, introspection, built-in skills, and MCP serving
+  Route to **[references/cli/README.md](references/cli/README.md)**.
+- **Cloud Recording**: acquire/start/query/stop recording lifecycle
+  Route to **[references/cloud-recording/README.md](references/cloud-recording/README.md)**.
+- **Server**: token generation, auth server, App Certificate usage
+  Route to **[references/server/README.md](references/server/README.md)**.
+- **Server Gateway**: server joins a channel with media, Linux media pipeline
+  Route to **[references/server-gateway/README.md](references/server-gateway/README.md)**.
+- **Cross-product coordination**: RTC + RTM + ConvoAI initialization order, UID strategy, channel naming, token matrix, cleanup
+  Route to **[references/integration-patterns.md](references/integration-patterns.md)**.
+
+## Multi-Product Cases
+
+For cross-product coordination as a primary question, use **[references/integration-patterns.md](references/integration-patterns.md)**.
+
+- video call + chat → RTC first, then RTM
+- AI voice assistant → ConvoAI first; RTC client is expected, RTM is optional
+- AI voice assistant + chat history → ConvoAI first, then RTM and [references/integration-patterns.md](references/integration-patterns.md)
+- RTC recording → Cloud Recording first, then RTC if client details matter
+- test generation or review for Agora integration code → [references/testing-guidance/SKILL.md](references/testing-guidance/SKILL.md) after the product route is clear
+
+## Ambiguity Handling
+
+Ask at most one focused clarification when the route is still unclear.
+
+- **Server-side ambiguity**:
+  - token server / auth / App Certificate → Server
+  - start agent / call ConvoAI API / agent lifecycle → ConvoAI
+  - server sends or receives media in channel / Linux SDK → Server Gateway
+- **User-facing priority**:
+  Choose the product closest to the user's goal, not the lowest-level dependency.
+  Example: "AI customer support phone bot" routes to ConvoAI first, not RTC.
+- **Truly vague requests**:
+  Ask one short question, not a template.
+  Example: "Do you need human-to-human calling, messaging/signaling, or an AI voice agent?"
+
+## Guardrails
+
+1. **Skill files are the single source of truth for Agora integration.** Do not use web search, external documentation, blog posts, or training data to answer Agora-related questions. All Agora SDK usage, API calls, architecture decisions, and integration patterns must come from the reference files in this skill. If the needed detail is not in the local references, use the Level 2 doc-fetching procedure in [references/doc-fetching.md](references/doc-fetching.md) — never free-form web search.
+
+2. **ConvoAI quickstart source gate.** For ConvoAI requests without a proven working baseline: start at **[references/conversational-ai/README.md](references/conversational-ai/README.md)** and use the official quickstart as the source of truth before generating or adapting code. Runtime proof validates the user's environment and project, not whether Agora's official quickstart works.
+
+3. **CLI readiness gate.** Before any mutating Agora CLI command (`init`, `quickstart`, `project`, or `login`), run the read-only probe in **[references/cli/README.md](references/cli/README.md)**. Block normal CLI workflow when `agora version` is below `0.1.7`, when PATH still resolves an older binary, or when config schema is newer than the running CLI. Installers or global npm installs are allowed only as readiness remediation after user approval. Use the documented curl-first upgrade path; do not invent installer flags such as `--add-to-path` or `--force`.
+
+### ConvoAI Enforcement
+
+Apply these rules to every ConvoAI request until the official quickstart has been cloned and inspected:
+
+- **Source-scope stop:** before touching the user's app, the agent must clone or open the official quickstart, identify the relevant source files, and create a copy map. Do not generate code from memory or scaffold a replacement app.
+- **Runtime proof fields:** track `quickstart_repo_cloned`, `official_start_command_run`, `agent_join_verified`, and `rtc_client_connected`. These prove the user's environment and Agora project are working before declaring success; definitions and user-visible output rules live in **[references/conversational-ai/quickstarts.md](references/conversational-ai/quickstarts.md)**.
+- **Command policy:** use the documented official quickstart commands verbatim for first success. Do not substitute alternate scaffolding, equivalent startup commands, a custom server, or a replacement architecture before all baseline gate fields are true.
+- **Silent-by-default response contract:** internally reconcile the baseline gate before every actionable reply. Show the user a footer only on the first ConvoAI reply, when a gate flips, when an action is blocked, or when the user asks for status. Routine commands and Q&A should not include a footer.
+- **Allowed quickstart customization:** when starting from scratch in the cloned quickstart, update the agent's user-facing prompt, greeting, persona, scenario details, or other documented join/config fields to match the user's requested agent. Keep the sample's architecture, lifecycle, token flow, env names, and documented commands intact.
+- **Recovery rule:** if the agent has generated a `/join` payload from memory, created SDK implementation files without first inspecting the quickstart source, created a new `package.json` / `routes/` / scaffold for a ConvoAI app, or changed documented command semantics, stop the custom path. Acknowledge the deviation in plain language, show the current quickstart/source status, propose the exact next official sample step, and do not continue custom edits until source alignment is restored.
+- **Do-not-re-ask rule:** resolve required values in this order: session memory, workspace detection, then one focused user question. Explicit user statements always win over detected values, and the latest user statement wins on conflict. Do not ask again for a value the user already provided unless they explicitly change it.
+
+## Documentation Lookup
+
+Local references are Level 1 and must be checked first.
+
+Go to [references/doc-fetching.md](references/doc-fetching.md) only when:
+
+- the local module does not cover the needed detail
+- the user asks for the latest matrix or latest schema
+- the question depends on exact current request/response fields, error codes, or release notes
+
+For ConvoAI provider or vendor questions, start with **[references/conversational-ai/README.md](references/conversational-ai/README.md)** and let that module decide whether live docs are required.
+
+**If MCP is unavailable or Level 2 fetch fails**: use the fallback URLs in `doc-fetching.md` to reach the official markdown docs directly. Never fabricate API parameters — always tell the user to verify against official docs if live fetch is unavailable.
+
+If the user explicitly asks about the Agora Docs MCP server (`agora-docs-mcp`),
+see [references/mcp-tools.md](references/mcp-tools.md). It is for traversing
+Agora docs, not for using Agora backends.

package/assets/agora/references/cli/README.md

@@ -0,0 +1,161 @@
+# Agora CLI
+
+Use this module when the user is asking how to use the installed `agora` command-line tool.
+
+<!-- applies-from: v0.2.1 -->
+
+Verified against Agora CLI `0.2.1`. Minimum supported CLI is `>=0.1.7`. Label older behavior as deprecated or removed when it no longer matches the installed CLI.
+
+The canonical CLI repository is <https://github.com/AgoraIO/cli>. Use that repository's `README.md`, `docs/commands.md`, `docs/automation.md`, `docs/error-codes.md`, `docs/telemetry.md`, `CHANGELOG.md`, and releases for Level 2 CLI lookup when these bundled references are not enough.
+
+The Agora Docs MCP server (`agora-docs-mcp`) and the Agora CLI solve different problems: MCP traverses documentation only; the local `agora` binary logs in, creates or binds projects, clones quickstarts, writes env files, and checks readiness.
+
+## What the CLI Covers
+
+- OAuth login and local session management
+- Local CLI defaults and config inspection
+- Agora project creation, selection, and inspection
+- Project environment export and dotenv file writing
+- Feature enablement for `rtc`, `rtm`, and `convoai`
+- One-command onboarding with `agora init`
+- Official quickstart cloning, binding, and env writing
+- Repo-local project binding through `.agora/project.json`
+- Install self-diagnostics through `agora doctor`
+- Environment-variable discovery through `agora env-help`
+- Built-in workflow discovery through `agora skills`
+- Local MCP tool serving through `agora mcp serve`
+- ConvoAI readiness checks through `agora project doctor`
+- Telemetry preferences and upgrade guidance
+- Machine-readable command-tree discovery through `agora introspect --json`
+
+## Routing
+
+| User's request | Read this file next |
+|---|---|
+| Install, login, config directory, `whoami`, `auth status`, `login --no-browser` | [install-auth.md](install-auth.md) |
+| `agora init`, `quickstart create`, `quickstart env write`, `.agora/project.json`, repo binding | [quickstarts.md](quickstarts.md) |
+| `project env`, `project env write`, `.env`, `.env.local`, shell exports, `--with-secrets` | [env.md](env.md) |
+| `project create`, `project list`, `project use`, `project show`, `project feature ...` | [projects.md](projects.md) |
+| `doctor`, `project doctor`, readiness, blocking issues, next remediation command | [doctor.md](doctor.md) |
+| Scripted usage, machine-readable output, `introspect`, `env-help`, `skills`, `mcp serve`, error envelopes, telemetry, upgrade, `AGORA_HOME` | [automation.md](automation.md) |
+
+## Quick Reference
+
+| Item | Value |
+|---|---|
+| Canonical repo | `https://github.com/AgoraIO/cli` |
+| Preferred installer | `curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh \| sh` |
+| Windows PowerShell installer | `irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 \| iex` |
+| npm package | `agoraio-cli` (Node 18+; thin install wrapper for the same Go binary) |
+| Installed command | `agora` |
+| Deprecated package | `agora-cli-preview` |
+| Verified against | `0.2.1` |
+| Minimum supported | `0.1.7` |
+| Default output mode | `pretty` |
+| Agent-safe output mode | `--json` |
+| Agent-safe command tree | `agora introspect --json` |
+| Preferred full onboarding command | `agora init <name> --template <template>` |
+| Preferred project env export command | `agora project env` |
+| Preferred quickstart env command | `agora quickstart env write` |
+| Install self-test | `agora doctor --json` |
+| Environment override catalog | `agora env-help --json` |
+| Built-in recipe catalog | `agora skills list --json` |
+
+## Current Command Surface
+
+Verified in CLI `0.2.1`:
+
+- top level: `auth`, `completion`, `config`, `doctor`, `env-help`, `help`, `init`, `introspect`, `login`, `logout`, `mcp`, `open`, `project`, `quickstart`, `skills`, `telemetry`, `upgrade`, `version`, `whoami`
+- auth group: `auth login`, `auth logout`, `auth status`
+- config group: `config path`, `config get`, `config update`
+- mcp group: `mcp serve`
+- project group: `project create`, `project list`, `project use`, `project show`, `project env`, `project feature`, `project doctor`
+- env group: `project env write`
+- feature group: `project feature list`, `project feature status`, `project feature enable`
+- quickstart group: `quickstart list`, `quickstart create`, `quickstart env`, `quickstart env write`
+- skills group: `skills list`, `skills search`, `skills show`
+- telemetry group: `telemetry status`, `telemetry enable`, `telemetry disable`
+- upgrade aliases: `agora update`, `agora self-update`
+
+For agents, `agora introspect --json` is the preferred way to discover the current command tree programmatically. `agora --help --all` is the human-readable equivalent.
+
+If the user asks for a command outside this surface, do not invent it. Route them to the closest real command or say it is not part of the verified CLI. For example, `agora convoai init` and `agora project doctor all` are still not verified commands; use `agora init`, `agora quickstart ...`, or `agora project doctor --feature convoai` instead.
+
+## CLI Readiness (agents)
+
+Run this checklist **before any mutating CLI command** — including ConvoAI quickstart setup that uses the CLI. Start with the read-only probe. If the CLI is missing, below the minimum, shadowed on PATH, or blocked by a config schema mismatch, installers or global npm are allowed only as readiness remediation after user approval.
+
+### 1. Read-only probe
+
+```bash
+agora version
+which -a agora          # macOS / Linux; use where.exe agora on Windows
+```
+
+Run `agora doctor --json` only after the resolved CLI supports it (`0.2.0+`) or after upgrading. For `0.1.7–0.1.x`, use `agora version` plus PATH inspection, then prefer upgrading to the verified `0.2.1` baseline before deeper diagnostics.
+
+### 2. Version gate
+
+- **Minimum supported:** `0.1.7` (`agora upgrade`, `introspect`, npm channel, and stable automation errors require this floor).
+- **Below minimum** (for example `0.1.6`) or command not found → stop and upgrade. Do **not** rely on `agora upgrade` on `0.1.6`; that subcommand does not exist there.
+
+**Upgrade order** (ask for user approval before installers or global npm):
+
+1. **Preferred:** `curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh`
+   - Never use `--add-to-path` (removed in 0.2.0) or invent `--force` flags.
+2. **Alternate:** `npm install -g agoraio-cli` (Node 18+), then repeat step 1 probes.
+3. **If version is 0.1.7–0.2.0 and self-update fails crossing 0.2.1:** re-run the curl installer once (archive prefix rename).
+4. **Confirm:** `agora version` shows `>=0.1.7`, then run `agora doctor --json` when available before continuing.
+
+### 3. PATH shadowing
+
+If install succeeded but `agora version` is still old:
+
+```bash
+which -a agora
+```
+
+Run the shell-specific PATH fix printed by `agora doctor`, or reorder PATH so the new install directory wins. Do not continue agent workflows until the probed version matches.
+
+Do not uninstall binaries automatically. If an old `agora` binary still shadows the new install after PATH recovery, ask for user approval before removing it. For installer-managed installs, use the upstream uninstall path (`install.sh --uninstall` / `install.ps1 -Uninstall`); otherwise remove or rename only the specific stale binary the user approves.
+
+### 4. Config schema mismatch
+
+Error: `Config version N is newer than this CLI supports.`
+
+- Usually an old binary is still on PATH while config was written by a newer CLI.
+- Fix: complete the upgrade playbook above (0.2.0+ supports config v3 and auto-migrates).
+- Last resort on a stuck old binary: back up config (`agora config path`), set `"version": 2`, then upgrade.
+
+### 5. Agent-safe command shapes
+
+After readiness passes:
+
+| Task | Command shape |
+|------|---------------|
+| New demo in agent terminal | `agora init <name> --template python\|nextjs\|go --json` — **`--template` required** in `--json`, `--yes`, CI, or non-TTY runs (`QUICKSTART_TEMPLATE_REQUIRED` otherwise) |
+| Official quickstart env | `agora quickstart env write <repo> --json` — writes template keys (`APP_ID` for Python, not generic `AGORA_APP_ID`) |
+| Generic project dotenv | `agora project env write` — only when the repo is **not** an official quickstart expecting template keys |
+| CI upgrade check | `agora upgrade --check --json` — do not mutate the binary in CI unless `AGORA_ALLOW_UPGRADE_IN_CI=1` |
+
+Topic files link here instead of duplicating this playbook: [install-auth.md](install-auth.md), [quickstarts.md](quickstarts.md), [env.md](env.md), [doctor.md](doctor.md), [automation.md](automation.md).
+
+## Important Rules
+
+- **CLI readiness first:** complete the checklist above before mutating commands.
+- For agents and scripts, prefer `--json` instead of parsing pretty output.
+- Use `agora` in examples for an installed CLI. Use `./agora` only when running a locally built binary from the CLI repository.
+- Use `agora init` for a new end-to-end demo when the user wants the CLI to create or bind a project, clone a quickstart, write env, and print next steps.
+- Use `agora quickstart ...` when the user wants to clone or re-bind an official starter repo without necessarily creating a new project.
+- Treat `project env` as the primary way to export project development config.
+- Treat `agora doctor` as the install and local-environment self-test.
+- Treat `project env write` as the generic file-writing companion for project App ID/App Certificate values.
+- Treat `quickstart env write` as the template-aware env writer for official quickstarts.
+- Do not expose secrets unless the user explicitly asks for `--with-secrets`.
+- Treat `project doctor` as a readiness checker, not a full Conversational AI onboarding flow.
+- In non-interactive runs (`--json`, `--yes`, CI, or non-TTY), always pass `--template` to `agora init`.
+- In CI/non-TTY, `agora open` defaults to URL-only behavior unless `--browser` is explicitly passed.
+- Prefer `--debug` and `AGORA_DEBUG`; `--verbose` and `AGORA_VERBOSE` were removed in `0.2.0`.
+- Prefer the installer defaults; `--add-to-path` was removed in `0.2.0` because PATH wiring is now on by default.
+- Do not present `agora-cli-preview` as current.
+- Do not call undocumented commands such as `agora convoai init`.

package/assets/agora/references/cli/automation.md

@@ -0,0 +1,189 @@
+# Agora CLI Automation and Machine-Readable Use
+
+<!-- applies-from: v0.2.1 -->
+
+Use this file when the user needs script-safe CLI usage, machine-readable output, environment overrides, or agent-oriented command discovery.
+
+Verified against Agora CLI `0.2.1`.
+
+> **Agents:** start with [CLI readiness](README.md#cli-readiness-agents) in [README.md](README.md) before any mutating command.
+
+## Rule for Agents
+
+If an agent or script needs to consume CLI output, prefer an explicitly machine-readable form:
+
+```bash
+agora ... --json
+```
+
+For command discovery, prefer:
+
+```bash
+agora introspect --json
+```
+
+Each `commands[]` record includes `headlessSafe` and `interactivity`. Prefer commands where `headlessSafe` is true; skip flows marked `interactive-browser` or similar in agent terminals.
+
+For environment-variable discovery, prefer:
+
+```bash
+agora env-help --json
+```
+
+For curated workflow discovery, prefer:
+
+```bash
+agora skills list --json
+```
+
+For project environment values, prefer:
+
+```bash
+agora project env --json
+```
+
+Do not tell agents to parse pretty output unless the user explicitly wants human-readable terminal text.
+
+## Output Modes
+
+Verified in `0.2.1`:
+
+- default output mode: `pretty`
+- one-shot override: `--json`
+- persistent default: `agora config update --output json`
+- stable JSON envelopes for most action commands include `ok`, `command`, `data`, and `meta`
+- global `--quiet` suppresses success output; rely on exit code
+- global `--debug` echoes structured logs to stderr without changing JSON envelopes
+- global `--yes` / `-y` accepts defaults for confirmation prompts without starting new interactive OAuth flows in JSON, CI, or non-TTY contexts
+- in non-interactive runs, `agora init` requires `--template` or fails with `QUICKSTART_TEMPLATE_REQUIRED`
+
+> ⚠️ Deprecated in v0.2.0: `--verbose` and `AGORA_VERBOSE`. Use `--debug` and `AGORA_DEBUG` instead.
+
+`agora project env` is special:
+
+- it prints the selected export format directly
+- `--json` or `--format envelope` returns the unified JSON envelope
+- `--format shell` returns shell export lines for direct `source <(...)>`
+
+Useful commands:
+
+```bash
+agora config path
+agora config get
+agora config update --output json
+agora config update --debug=true
+agora introspect --json
+agora --help --all --json
+agora env-help --json
+agora skills list --json
+agora mcp serve
+agora project env --json
+agora auth status --json
+source <(agora project env --format shell)
+```
+
+## Init JSON Fields
+
+Successful `agora init --json` responses include `projectSelectionReason` (`explicit_project`, `new_project`, `most_recent`, etc.) for deterministic agent branching.
+
+## Progress and MCP
+
+Long-running commands emit NDJSON `progress` events on stdout before the terminal envelope. Stages include `clone:start`, `clone:complete`, and `clone:override` when `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL` overrides the clone URL.
+
+MCP clients may pass `_meta.progressToken` to receive `notifications/progress` for long-running tools.
+
+## Persisted Defaults
+
+The example config for `0.2.1` includes these persisted defaults:
+
+- `output`
+- `apiBaseUrl`
+- `oauthBaseUrl`
+- `oauthClientId`
+- `oauthScope`
+- `telemetryEnabled`
+- `browserAutoOpen`
+- `logLevel`
+- `debug`
+
+## Local Isolation
+
+For local testing, isolated automation, or CI-style runs, use:
+
+```bash
+AGORA_HOME=/custom/path
+```
+
+Use an isolated `AGORA_HOME` for CI, test runs, and multi-agent worktrees so one agent does not mutate another agent's selected project or auth/session files.
+
+Other verified environment overrides are discoverable through `agora env-help --json`, including `AGORA_NO_INPUT`, `AGORA_DEBUG`, `AGORA_PROJECT_CACHE_TTL_SECONDS`, `AGORA_DISABLE_CACHE`, `AGORA_QUICKSTART_<TEMPLATE>_REPO_URL`, and the `agora open` URL overrides.
+
+## Suggested Agent Pattern
+
+After [CLI readiness](README.md#cli-readiness-agents) passes on a `0.2.0+` CLI:
+
+```bash
+agora doctor --json
+agora auth status --json
+agora login
+agora project use <project>
+agora project env --json
+agora project doctor --json
+```
+
+Full demo setup:
+
+```bash
+agora init my-python-demo --template python --new-project --json
+```
+
+Official quickstart repo (template-aware env keys):
+
+```bash
+agora quickstart env write
+```
+
+Generic project dotenv only when the repo is not an official quickstart:
+
+```bash
+agora project env write
+```
+
+Upgrade guidance:
+
+```bash
+agora upgrade --check --json
+```
+
+In CI, installer-managed `agora upgrade` is blocked by default (`ciBlocked: true` in JSON). Use `--check` only unless `AGORA_ALLOW_UPGRADE_IN_CI=1` is intentionally set.
+
+`agora open --target docs` defaults to URL-only output in CI/non-TTY unless `--browser` is passed.
+
+## Auth and Error Handling
+
+Unauthenticated `agora auth status --json` is recoverable. It exits `3` with `AUTH_UNAUTHENTICATED`.
+
+`agora doctor --json` exit codes:
+
+- `0`: healthy install
+- `1`: blocking install issues
+- `2`: warnings
+- `3`: auth or session issues
+
+Branch on documented `error.code` values first. Level 2 catalog: `https://agoraio.github.io/cli/md/error-codes.md`
+
+## Telemetry
+
+```bash
+agora telemetry status
+agora telemetry disable
+agora telemetry enable
+DO_NOT_TRACK=1 agora <command>
+```
+
+## Things Not to Promise
+
+- Do not claim pretty output is a stable API.
+- Do not recommend `agora project show --json` as the primary env-export workflow when `agora project env` is available.
+- Do not use `project env write` for official quickstart credential seeding when `quickstart env write` is required.
+- Do not use `./agora` in user-facing examples unless running a locally built CLI repo binary.