Add structured docs/ directory and copilot instructions for documentation maintenance (#7208)

* Initial plan

* Add structured docs/ directory, copilot instructions, and update README

Create docs/ at repo root with concepts/, guides/, reference/, and
architecture/ subdirectories. Add initial documentation covering:

- Glossary, feature stages, alpha features (concepts)
- Contributing, adding commands, creating extensions, observability (guides)
- Environment variables, azure.yaml schema, feature status (reference)
- System overview, command execution, extension framework, provisioning (architecture)
- ADR template for future architecture decision records

Add .github/instructions/documentation.instructions.md with copilot
instructions to keep docs up to date when codebase changes.

Update root README.md to link to the new docs/ directory.

Co-authored-by: spboyer <7681382+spboyer@users.noreply.github.com>

* Address code review: alphabetize feature status, improve action docs

Co-authored-by: spboyer <7681382+spboyer@users.noreply.github.com>

* fix: resolve cspell failures and review feedback

- Add cspell overrides for technical terms in docs/ markdown files
- Fix Jaeger OTLP endpoint to use explicit http://localhost:4318
- Update AGENTS.md link in README.md to root (symlink)
- Verified errors.AsType is valid (Go 1.26, used in 10+ files)
- Verified table syntax is correct (no || issues found)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore: retrigger CI

* Address review feedback: fix env vars, add pflag import, improve auth descriptions

- Remove hallucinated AZD_DEBUG_DOTENV_OVERRIDES, replace with real AZD_DEBUG_LOG
- Move AZD_AUTH_ENDPOINT/AZD_AUTH_KEY to new "IDE Integration" section with
  accurate descriptions (set by IDE hosts, not user-facing)
- Add missing github.com/spf13/pflag import to code example in adding-a-new-command.md

Agent-Logs-Url: https://github.com/Azure/azure-dev/sessions/6fcebb42-32ec-4d91-a394-7e4f5b46a3fd

Co-authored-by: hemarina <104857065+hemarina@users.noreply.github.com>

* Fixes:
 - extension-framework, creating-an-extension, glossary: correct
   capability names to match extension.schema.json (custom-commands,
   lifecycle-events, mcp-server, service-target-provider,
   framework-service-provider, metadata)
 - creating-an-extension: fix extension ID (microsoft.azd.extensions),
   YAML field (id: not name:), list all supported languages
 - command-execution-model: fix OutputFormat types, ActionResult
   description, add NoneFormat
 - adding-a-new-command: fix Bind signature, file path, root.Add
 - system-overview: fix IoC pattern to constructor injection
 - provisioning-pipeline: remove hallucinated preflight checks
 - azure-yaml-schema: fix host values (ai.endpoint, azure.ai.agent),
   add missing properties, hooks, languages, service fields
 - environment-variables: fix AZD_DEBUG_LOG description
 - feature-status: add missing commands, match canonical naming
 - alpha-features: add unset/disable commands, env var notation
 - feature-stages: fix graduation criteria per canonical source
 - observability: fix Span/Event terminology, add localhost note
 - glossary: fix preflight checks to include server-side validation

* misc

* add azure.yaml schema

* docs: address Copilot review — fix output formatting docs, gofmt code, TTY description, add AZD_AUTH_CERT

- command-execution-model.md: clarify OutputFormats wires flags only;
  actions emit structured output via injected output.Formatter
- adding-a-new-command.md: convert code example to tab indentation
  (gofmt), add note that OutputFormats alone is insufficient
- feature-status.md: remove misleading 'with graduation criteria'
  from link text
- environment-variables.md: fix AZD_FORCE_TTY description to
  'terminal detection mode', add missing AZD_AUTH_CERT env var

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: address jongio round 4 — add ai_model_quota check, shell→kind, fix IoC regression, update glossary

- provisioning-pipeline.md: add ai_model_quota as second preflight check
- azure-yaml-schema.md: shell→kind in hook example, add infracreate/infradelete hooks
- system-overview.md: fix IoC example regression (MustRegisterTransient→MustRegisterSingleton)
- glossary.md: update preflight description to match implemented checks

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Update docs/reference/azure-yaml-schema.md

Co-authored-by: Jon Gallant <2163001+jongio@users.noreply.github.com>

* Update docs/concepts/glossary.md

Co-authored-by: Jon Gallant <2163001+jongio@users.noreply.github.com>

* Update docs/architecture/system-overview.md

Co-authored-by: Jon Gallant <2163001+jongio@users.noreply.github.com>

* docs: add reserved_resource_names to preflight check list

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* address feedback

* Update docs/README.md

Co-authored-by: Jon Gallant <2163001+jongio@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: spboyer <7681382+spboyer@users.noreply.github.com>
Co-authored-by: Shayne Boyer <spboyer@live.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: hemarina <104857065+hemarina@users.noreply.github.com>
Co-authored-by: hemarina <hemarina@microsoft.com>
Co-authored-by: Jon Gallant <2163001+jongio@users.noreply.github.com>

Author: 5 people

.github/instructions/documentation.instructions.md

@@ -0,0 +1,44 @@
+# Documentation Maintenance
+
+This repository uses a structured documentation system under `docs/` at the repo root.
+When making changes to the codebase, keep the documentation current.
+
+## Documentation Structure
+
+```text
+docs/
+├── README.md          — Documentation index and navigation
+├── concepts/          — Core mental models, terminology, feature lifecycle
+├── guides/            — Task-oriented how-tos for contributors
+├── reference/         — Schemas, flags, environment variables, feature status
+└── architecture/      — System overviews, design context, ADRs
+```
+
+## When to Update Documentation
+
+- **New command or flag:** Update `docs/guides/adding-a-new-command.md` if the pattern changes; update `docs/reference/feature-status.md` with the new feature's stage.
+- **New environment variable:** Add it to `docs/reference/environment-variables.md`.
+- **New extension capability:** Update `docs/architecture/extension-framework.md` and `docs/guides/creating-an-extension.md`.
+- **Feature stage change:** Update `docs/reference/feature-status.md` when a feature graduates (alpha → beta → stable).
+- **New concept or term:** Add it to `docs/concepts/glossary.md`.
+- **Architecture decision:** Create a new ADR using the template at `docs/architecture/adr-template.md`.
+- **New hosting target or language:** Update `docs/reference/feature-status.md` and `docs/concepts/glossary.md`.
+
+## Documentation Placement Guide
+
+| Content type | Location |
+|---|---|
+| Term or concept definition | `docs/concepts/glossary.md` |
+| Contributor how-to | `docs/guides/` |
+| Configuration reference | `docs/reference/` |
+| System design or ADR | `docs/architecture/` |
+| Implementation design details | `cli/azd/docs/design/` |
+| Extension development details | `cli/azd/docs/extensions/` |
+| Code style standards | `cli/azd/docs/style-guidelines/` |
+
+## Documentation Standards
+
+- Use clear, concise language
+- Link to detailed implementation docs in `cli/azd/docs/` rather than duplicating content
+- Keep tables and lists scannable
+- Include code examples where they aid understanding

.vscode/cspell.misc.yaml

@@ -72,3 +72,29 @@ overrides:
           - azureai
           - entra
           - flexconsumption
+    - filename: docs/architecture/**/*.md
+      words:
+          - azapi
+          - Errorf
+          - grpcbroker
+          - vsrpc
+    - filename: docs/guides/**/*.md
+      words:
+          - errorlint
+          - Errorf
+          - gofmt
+          - golangci
+          - gosec
+          - jaegertracing
+          - mycommand
+          - mypackage
+          - pflag
+          - staticcheck
+          - stdlib
+          - vsrpc
+    - filename: docs/reference/**/*.md
+      words:
+          - appservice
+          - Buildpacks
+          - containerapp
+          - staticwebapp

README.md

@@ -27,7 +27,7 @@
 
 ## 🤖 AI Agents
 
-**Contributing to this repo?** See [AGENTS.md](cli/azd/AGENTS.md) for coding standards and guidelines.
+**Contributing to this repo?** See [AGENTS.md](AGENTS.md) for coding standards and [docs/](docs/README.md) for contributor documentation.
 
 **Using `azd` with an AI coding assistant?** Check out the [docs](https://aka.ms/azd) and [templates](https://azure.github.io/awesome-azd/).
 

docs/README.md

@@ -0,0 +1,63 @@
+# Azure Developer CLI Documentation
+
+> Internal documentation for contributors and AI coding agents working on the Azure Developer CLI (`azd`).
+
+For end-user documentation, see [aka.ms/azd](https://aka.ms/azd). For template examples, see [awesome-azd](https://azure.github.io/awesome-azd/).
+
+---
+
+## Concepts
+
+Core mental models, terminology, and feature lifecycle.
+
+- [Glossary](concepts/glossary.md) — Key terms and concepts used throughout the codebase
+- [Feature Stages](concepts/feature-stages.md) — How features graduate from alpha → beta → stable
+- [Alpha Features](concepts/alpha-features.md) — How experimental features are gated and discovered
+
+## Guides
+
+Task-oriented how-tos for common contributor workflows.
+
+- [Contributing](../CONTRIBUTING.md) — How to build, test, lint, and submit changes
+- [Adding a New Command](guides/adding-a-new-command.md) — End-to-end walkthrough for new CLI commands
+- [Creating an Extension](guides/creating-an-extension.md) — How to build and publish an azd extension
+- [Observability and Tracing](guides/observability.md) — Adding telemetry, traces, and debugging
+
+## Reference
+
+Schemas, flags, environment variables, and configuration details.
+
+- [Environment Variables](reference/environment-variables.md) — All environment variables that configure azd behavior
+- [azure.yaml Schema](reference/azure-yaml-schema.md) — Project configuration file reference
+- [Feature Status](reference/feature-status.md) — Current maturity status of all features
+
+## Architecture
+
+System overviews, design context, and decision records.
+
+- [System Overview](architecture/system-overview.md) — High-level architecture and code organization
+- [Command Execution Model](architecture/command-execution-model.md) — How commands are registered, resolved, and run
+- [Extension Framework](architecture/extension-framework.md) — gRPC-based extension system architecture
+- [Provisioning Pipeline](architecture/provisioning-pipeline.md) — How infrastructure provisioning works
+- [ADR Template](architecture/adr-template.md) — Template for lightweight architecture decision records
+
+---
+
+## Where do new docs go?
+
+| You want to document… | Put it in… |
+|---|---|
+| A new term or concept | `docs/concepts/glossary.md` |
+| A how-to for contributors | `docs/guides/` |
+| A configuration reference | `docs/reference/` |
+| A system design or ADR | `docs/architecture/` |
+| Detailed implementation design | `cli/azd/docs/design/` |
+| Extension development details | `cli/azd/docs/extensions/` |
+| Style and coding standards | `cli/azd/docs/style-guidelines/` |
+
+## Related documentation
+
+- [AGENTS.md](../AGENTS.md) — AI agent coding instructions
+- [cli/azd/docs/](../cli/azd/docs/) — Detailed implementation-level documentation
+- [cli/azd/docs/style-guidelines/](../cli/azd/docs/style-guidelines/) — Code style guide
+- [cli/azd/docs/extensions/](../cli/azd/docs/extensions/) — Extension framework details

docs/architecture/adr-template.md

@@ -0,0 +1,35 @@
+# ADR Template
+
+Use this template to record lightweight architecture decisions. ADRs document the context, decision, and consequences of significant technical choices.
+
+## How to Use
+
+1. Copy this template to a new file: `docs/architecture/adr-NNN-title.md`
+2. Fill in each section
+3. Submit as part of the PR that implements the decision
+
+ADRs are immutable once accepted. If a decision is superseded, create a new ADR that references the original.
+
+---
+
+## ADR-NNN: [Title]
+
+**Status:** Proposed | Accepted | Superseded by [ADR-NNN]
+
+**Date:** YYYY-MM-DD
+
+### Context
+
+What is the issue that we're seeing that is motivating this decision or change?
+
+### Decision
+
+What is the change that we're proposing and/or doing?
+
+### Consequences
+
+What becomes easier or more difficult to do because of this change?
+
+### Alternatives Considered
+
+What other approaches were evaluated, and why were they not chosen?

docs/architecture/command-execution-model.md

@@ -0,0 +1,86 @@
+# Command Execution Model
+
+How CLI commands are registered, resolved, and executed in azd.
+
+## Pipeline Overview
+
+```text
+ActionDescriptor → CobraBuilder → Cobra Command → Middleware → Action.Run()
+```
+
+### 1. ActionDescriptor Registration
+
+Commands are declared in `cmd/root.go` as a tree of ActionDescriptors:
+
+```go
+root := actions.NewActionDescriptor("azd", nil)
+
+root.Add("up", &actions.ActionDescriptorOptions{
+    Command:        newUpCmd(),
+    ActionResolver: newUpAction,
+    FlagsResolver:  newUpFlags,
+    OutputFormats:  []output.Format{output.JsonFormat, output.NoneFormat},
+})
+```
+
+Each descriptor specifies:
+
+- **Command** — Cobra command metadata (name, description, examples)
+- **ActionResolver** — Factory function to create the action via IoC
+- **FlagsResolver** — Factory function to create the flags struct
+- **OutputFormats** — Supported output formats (JSON, table, none)
+
+### 2. CobraBuilder
+
+At startup, the CobraBuilder walks the ActionDescriptor tree and generates standard Cobra commands. This decouples command definition from Cobra's API.
+
+### 3. Middleware Pipeline
+
+Before an action runs, the middleware chain processes cross-cutting concerns:
+
+| Middleware | Purpose |
+|---|---|
+| Telemetry | Creates root span, records command events and attributes |
+| Hooks | Executes pre/post lifecycle hooks from `azure.yaml` |
+| Extensions | Routes events to registered extensions |
+| Debug | Handles `--debug` flag behavior |
+
+Middleware is registered in `cmd/middleware/` and composed as a chain around the action.
+
+### 4. Action Execution
+
+Actions implement the `actions.Action` interface:
+
+```go
+type Action interface {
+    Run(ctx context.Context) (*ActionResult, error)
+}
+```
+
+The `ActionResult` contains a `Message *ResultMessage` field displayed to the user. There is no separate structured-data field — output formatting is handled by the middleware and formatter pipeline, not through `ActionResult`. Actions receive dependencies via constructor injection through the IoC container.
+
+### 5. Output Formatting
+
+`OutputFormats` declares which output modes a command supports and wires up flags such as `--output` and `--query`. Structured output is not derived from `ActionResult` — actions that need JSON or table output inject an `output.Formatter` dependency and emit it themselves within `Run()`. `ActionResult` carries only the user-facing UX message.
+
+Supported formats:
+
+- **JSON** — The action writes structured JSON through the formatter
+- **Table** — The action writes tabular output through the formatter
+- **None** — Only the `ActionResult` message is displayed
+
+## Error Handling
+
+- Actions return errors wrapped with `fmt.Errorf("context: %w", err)`
+- `internal.ErrorWithSuggestion` adds user-facing fix suggestions
+- The middleware pipeline catches and formats errors for display
+- Context cancellations are handled gracefully
+
+## Adding a New Command
+
+See [Adding a New Command](../guides/adding-a-new-command.md) for a step-by-step guide.
+
+## Detailed Reference
+
+- [cli/azd/docs/style-guidelines/new-azd-command.md](../../cli/azd/docs/style-guidelines/new-azd-command.md) — Full implementation reference
+- [Guiding Principles](../../cli/azd/docs/style-guidelines/guiding-principles.md) — Command design philosophy

docs/architecture/extension-framework.md

@@ -0,0 +1,93 @@
+# Extension Framework
+
+Architecture of the gRPC-based extension system in azd.
+
+## Overview
+
+Extensions are external processes that communicate with azd via gRPC. They allow third parties and first-party teams to add new capabilities — languages, hosting targets, event handlers, and more — without modifying the core CLI.
+
+## Architecture
+
+```text
+azd (host)
+  ├── Extension Registry (discovery)
+  ├── Extension Manager (lifecycle)
+  └── gRPC Broker (communication)
+        ↕ gRPC
+      Extension Process
+        ├── Capability Handlers
+        └── Service Implementations
+```
+
+### Discovery
+
+Extensions are discovered from registries — JSON manifests that list available extensions with their versions, capabilities, and download URLs.
+
+- **Official registry:** `https://aka.ms/azd/extensions/registry`
+- **Dev registry:** `https://aka.ms/azd/extensions/registry/dev` (unsigned builds)
+- **Local sources:** File-based manifests for development
+
+### Lifecycle
+
+1. User installs an extension: `azd extension install <name>`
+2. Extension binary is downloaded and cached locally
+3. When needed, azd spawns the extension process
+4. gRPC connection is established via the broker
+5. azd invokes capability methods on the extension
+6. Extension responds via gRPC
+
+### Communication
+
+The gRPC broker (`pkg/grpcbroker`) manages bidirectional communication. Extensions can both:
+
+- **Receive calls** from azd (e.g., "build this service")
+- **Make calls** back to azd (e.g., "prompt the user", "read environment config")
+
+## Capabilities
+
+Extensions declare their capabilities in `extension.yaml`:
+
+| Capability | Description |
+|---|---|
+| `custom-commands` | Expose new command groups and commands to azd |
+| `lifecycle-events` | Subscribe to azd project and service lifecycle events (pre/post provision, deploy, etc.) |
+| `mcp-server` | Provide Model Context Protocol tools for AI agents |
+| `framework-service-provider` | Add build/restore support for new languages |
+| `service-target-provider` | Add deployment support for new hosting targets |
+| `metadata` | Provide metadata about commands and capabilities |
+
+## Available gRPC Services
+
+Extensions can access these azd services via gRPC:
+
+- **Project** — Read project configuration
+- **Environment** — Read/write environment values and secrets
+- **User Config** — Read user-level azd configuration
+- **Deployment** — Access deployment information
+- **Account** — Access Azure account details
+- **Prompt** — Display prompts and collect user input
+- **AI Model** — Query AI model availability and quotas
+- **Event** — Subscribe to and emit events
+- **Container** — Container registry operations
+- **Framework** — Framework service operations
+- **Service Target** — Deployment target operations
+
+## Error Handling
+
+Extensions use two structured error types:
+
+- **`ServiceError`** — For Azure API or remote service errors
+- **`LocalError`** — For client-side validation or configuration errors
+
+Error precedence: ServiceError → LocalError → azcore.ResponseError → gRPC auth → fallback
+
+## First-Party Extensions
+
+First-party extensions live in `cli/azd/extensions/` and are registered in `cli/azd/extensions/registry.json`.
+
+## Detailed Reference
+
+- [Extension Framework Guide](../../cli/azd/docs/extensions/extension-framework.md) — Getting started
+- [Extension Framework Services](../../cli/azd/docs/extensions/extension-framework-services.md) — Adding language support
+- [Extensions Style Guide](../../cli/azd/docs/extensions/extensions-style-guide.md) — Design guidelines
+- [Creating an Extension](../guides/creating-an-extension.md) — Step-by-step guide