Add az connector-namespace CLI documentation + install tooling

[DevArjun23]

What

Adds the customer-facing documentation, AI-agent integration guide, and install tooling for the az connector-namespace Azure CLI extension. The wheel itself ships through GitHub Releases on this repo. By default the install scripts fetch the latest published wheel via the https://aka.ms/connector-namespace.whl redirect; a specific version can still be pinned per-call.

The layout follows the microsoft/azure-container-apps early-access pattern: one landing README, one complete-reference, install scripts, AI-agent guide, and runnable examples.

Directory layout

public-preview/connector-namespace-cli/
  README.md                  Prereqs + Install + Quick Start + Deep Dive + Reference
  complete-reference.md      Full command reference + auth + arg shapes + tips & gotchas
  install.sh                 curl | sh installer (Linux / macOS)
  install.ps1                irm | iex installer (Windows)
  AGENTS.md                  Guide for AI assistants
  examples/                  5 runnable bash scripts

Plus a one-line update to root README.md adding the CLI to the Resources section.

How customers install

Default install fetches the latest published wheel via the https://aka.ms/connector-namespace.whl redirect (the script downloads it to a temp file, then installs from the local file):

• Linux/macOS: curl one-liner from public-preview/connector-namespace-cli/install.sh
• Windows: irm one-liner from public-preview/connector-namespace-cli/install.ps1

Version pinning per-call via the CONNECTOR_NAMESPACE_VERSION env var (sh) or -Version parameter (ps1), which resolves to the matching GitHub Release asset URL.

Direct no-script install:

az extension add --upgrade --yes --source https://github.com/Azure/Connectors/releases/download/v1.0.0b9/connector_namespace-1.0.0b9-py3-none-any.whl

The aka.ms/connector-namespace.whl redirect is the single source of truth for the default install; bumping it requires no change to the scripts.

Command surface

9 sub-groups, 45 commands rooted at az connector-namespace: namespace, identity, connection, connection access-policy, mcp-connector, mcp-connector access-policy, trigger (+ run + status), connector catalog, managed-mcp-operation catalog. Full reference in public-preview/connector-namespace-cli/complete-reference.md.

What the AI agent guide does

public-preview/connector-namespace-cli/AGENTS.md follows the AGENTS.md community convention. Contains: decision tree (intent -> command), authentication-mode matrix, argument-shape cheat sheet, asymmetry traps, common-error -> fix table, rules of engagement, and refusal rules.

Verification

• All docs cross-link correctly within public-preview/connector-namespace-cli/
• Install scripts tested locally (default install, version pinning, uninstall, verify)
• Every documented command and arg cross-checked against the aaz module surface; second-pass audit caught and fixed 5 correctness bugs
• All inline review comments addressed and threads resolved

Out of scope

• The wheel binary (cut as a separate GitHub Release - v1.0.0b9 is live)
• learn.microsoft.com docs publishing (future)
• Code-signing pipeline (future)

[Copilot]

Pull request overview

This PR onboards the customer-facing az connector Azure CLI extension into the repo as a downloadable preview wheel, accompanied by a full set of human and AI-agent documentation plus runnable bash examples. It is purely additive (one line added to the root README) and does not change any product code in this repository; the purpose is to provide a public install channel and authoritative usage docs for managing Microsoft.Web/connectorGateways from the CLI.

Changes:

• Adds a cli/ tree with README, AGENTS.md (AI-agent guide), preview wheel, and docs (quickstart, cookbook, authentication, commands, troubleshooting).
• Adds six runnable example scripts covering bootstrap, OAuth consent, access grants, OBO/hosted MCP, and webhook triggers.
• Adds a single bullet to the root README.md linking to the new CLI directory.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Adds a Resources bullet linking to the new CLI extension directory.
cli/README.md	Customer landing page: install/uninstall, quick tour, concepts, links to docs.
cli/AGENTS.md	AI-agent guide: decision tree, rules of engagement, auth-mode matrix, asymmetry traps.
cli/docs/quickstart.md	5-minute end-to-end walkthrough creating a namespace, connection, MCP connector, and API key.
cli/docs/cookbook.md	Ten end-to-end bash recipes for common scenarios.
cli/docs/authentication.md	Deep dive on API key / access key / managed identity / connection-credential models, and access policies.
cli/docs/commands.md	Full command reference table (states 37 commands; tables sum to 47 — flagged).
cli/docs/troubleshooting.md	Eleven common errors with explanations and fixes.
cli/examples/01-bootstrap.sh	Creates RG, namespace, and an Office 365 connection.
cli/examples/02-consent-flow.sh	Two-step OAuth consent (generate link, then exchange code).
cli/examples/03-grant-access.sh	Grants an Entra ID principal access to a connection.
cli/examples/04-obo-mcp-connector.sh	Creates an OBO MCP connector; references a missing 04-grant-mcp-access.sh — flagged.
cli/examples/05-hosted-mcp-server.sh	Creates a hosted-MCP-server MCP connector with FIC + admin app reg.
cli/examples/06-webhook-trigger.sh	Creates a webhook trigger and prints inspection commands.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

[DevArjun23]

Addressed reviewer comments

Pushed 70fef4c with fixes for all 5 distinct issues raised across the 3 review rounds (12 inline comments total, mostly duplicates of the same 5 root causes):

#	Issue	File(s)	Fix
1	Command count: doc says 37, subtotals add to 47	cli/docs/commands.md:121,130, cli/AGENTS.md:16	Recounted actual aaz tree → 45 commands; updated totals + subtotals consistently
2	managed-api and managed-hosted-mcp-connector references for groups that no longer exist in the aaz tree (renamed/dropped during workspace cleanup)	cli/docs/commands.md, cli/AGENTS.md, cli/docs/cookbook.md, cli/docs/troubleshooting.md, cli/examples/05-hosted-mcp-server.sh	managed-api → connector rename; hosted-MCP-server discovery now documented as portal-only for v1 (no CLI surface in this release)
3	Reference to non-existent 04-grant-mcp-access.sh	cli/examples/04-obo-mcp-connector.sh:23	Dropped the script reference; replaced with a pointer to cookbook Recipe 4 + a note explaining the access-policy schema difference between connections and mcp-connectors
4	date -u -d '90 days' is GNU coreutils only (breaks on macOS/BSD)	cli/docs/cookbook.md:199	Added the equivalent macOS form (date -u -v+90d ...) as an inline comment
5	Root README.md still said az connector ... after the rename	README.md:16	Updated to az connector-namespace ...

Bonus: Reconciled --connection-details shorthand keys in cli/AGENTS.md:124 to match the JSON column (camelCase connectionName/connectorName), fixing the third minor inconsistency Copilot called out.

Marking review threads resolved.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[DevArjun23]

Status update — docs restructure complete

Pushed 9bf3b53 reorganizing the docs to mirror the
microsoft/azure-container-apps early-access layout.

New directory layout

docs/early/cli/
├─ README.md                                            Prereqs + Install + Quick Start + Deep Dive + Reference
├─ complete-reference.md                                Full 45-command reference + auth + arg shapes + tips & gotchas
├─ install.sh                                           curl | sh installer (Linux / macOS)
├─ install.ps1                                          irm | iex installer (Windows)
├─ latest-version.txt                                   1.0.0b9 (single-source-of-truth)
├─ AGENTS.md                                            (unchanged) Guide for AI assistants
└─ examples/                                            (unchanged) 6 runnable bash scripts

Customer install — now a one-liner

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/Azure/Connectors/main/docs/early/cli/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/Azure/Connectors/main/docs/early/cli/install.ps1 | iex

The installer reads latest-version.txt (or $CONNECTOR_NAMESPACE_VERSION env var) → builds the GitHub Release wheel URL → runs az extension add --upgrade --yes --source <url> → verifies. Supports --uninstall.

What changed under the hood

• Moved cli/ → docs/early/cli/ (preserves git history)
• Added install.sh, install.ps1, latest-version.txt
• Rewrote README.md in ACA style: Prereqs · Install · Quick Start (end-to-end script) · Deep Dive (11 capability sections, folding the old cookbook) · Reference
• Created complete-reference.md: full command tree (45 commands), authentication deep dive, JSON-vs-shorthand cheat sheet, output formats, all 9 tips & gotchas, Entra ID discovery snippets
• Deleted docs/early/cli/docs/{quickstart,cookbook,authentication,commands,troubleshooting}.md — content folded into the two main docs
• Updated root README.md link → ./docs/early/cli/

Follow-up after merge

1. Cut GitHub Release v1.0.0b9 with connector_namespace-1.0.0b9-py3-none-any.whl attached (the install scripts will then resolve)

[DevArjun23]

Update: aka.ms shortlink + internal code-review fixes

Pushed 2d8cf37 with two changes:

Distribution: https://aka.ms/connector-namespace-whl as the canonical URL

The install scripts and docs now default to the aka.ms shortlink, which redirects to the latest published wheel. The aka.ms target is updated on every release. Specific-version installs still resolve to the GitHub Release asset URL via CONNECTOR_NAMESPACE_VERSION (sh) or -Version (ps1). Dropped docs/early/cli/latest-version.txt - it's no longer the source of truth.

Direct install (no scripts):
az extension add --upgrade --yes --source https://aka.ms/connector-namespace-whl

Code-review findings addressed

Internal review caught four issues, all fixed in the same commit:

• Critical: --scope on list-api-key is a plain string AAZStrArg (the MCP server config name), not the '{""mcpServerConfigName"":""...""}' JSON wrapper the docs claimed. Wrong shape would silently scope the key to a non-existent config. Fixed all 5 occurrences across README and complete-reference.
• High: AGENTS.md still linked to ./docs/{commands,cookbook,authentication,troubleshooting}.md (deleted in the restructure). Repointed to README + complete-reference anchors.
• Medium: All 6 examples/*.sh referenced cookbook.md recipes (deleted); 04-obo-mcp-connector.sh also referenced docs/authentication.md. Repointed to ../README.md sections.
• Low: install.sh --help relied on sed -n on \ which is sh (or -) when invoked via the documented curl | sh pattern. Removed the branch entirely.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

[DevArjun23]

Update: command/arg correctness audit against the aaz module

Pushed bca7b2c with 5 fixes from a second-pass audit that diffed every documented az connector-namespace invocation against the aaz-generated schema files.

#	Sev	Bug	Where	Fix
1	Critical	trigger run / trigger status documented as --trigger-name; the aaz schema declares the (required) flag as --trigger-config-name	README:353-355, examples/06-webhook-trigger.sh:24-25	Renamed to --trigger-config-name
2	Critical	--connectors '[{""connectorName"":""...""}]' references a field that doesn't exist; the actual --connectors[] element fields are connectionName, description, displayName, name, operations	README/AGENTS/complete-reference/04-obo-mcp-connector.sh	For OnBehalfOfUser: use name (the managed connector id, e.g. sql). For shared/Developer/AppOnly: keep connectionName. Updated all 3 auth-mode matrices
3	High	connection update --tags doesn't exist (schema only accepts --connector-name and --display-name)	README:210, complete-reference:167/394	Replaced with --display-name; fixed reference tables
4	High	connector-namespace update --api-hub-environment-id is hidden by the TagOnlyNamespaceUpdate recipe — only --tags reaches the wire	complete-reference:147/393/446	Updated command-tree, update-semantics table, and the ""blank tags workaround"" gotcha
5	Medium	Error message text said connectorName but AAZ normalizes to snake_case before raising, so runtime error reads connector_name	3 places	Updated error strings

All 5 issues verified against Q:\\dev\\worktrees\\azure-cli-extensions\\AddConnectorsExtension\\src\\connector-namespace\\azext_connector_namespace\\aaz\\latest\\connector_namespace\\ (the source aaz tree) and sdks/python/azure-cli-connector-namespace/azext_connector_namespace/custom.py on adc-devx main (the recipe layer).

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

[apranaseth]

why are we putting them under early?

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.