Add structured docs/ directory and copilot instructions for documentation maintenance

.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

@@ -36,3 +36,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](guides/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,84 @@
+# 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:  []actions.OutputFormat{actions.OutputFormatJson},
+})
+```
+
+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` (displayed to the user) and optional structured data used by output formatters (JSON, table). Actions receive dependencies via constructor injection through the IoC container.
+
+### 5. Output Formatting
+
+When a command supports `--output`, the framework formats the `ActionResult`:
+
+- **JSON** — Serializes the result data as JSON
+- **Table** — Renders the result data as a formatted table
+- **None** — Displays only the result message
+
+## 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,92 @@
+# 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 |
+|---|---|
+| `event-handler` | React to lifecycle events (pre/post provision, deploy, etc.) |
+| `framework-service-provider` | Add build/restore support for new languages |
+| `service-target-provider` | Add deployment support for new hosting targets |
+| `compose-provider` | Custom orchestration logic |
+| `workflow-provider` | Custom workflow steps |
+
+## 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