Add structured docs/ directory and copilot instructions for documentation maintenance

[Copilot]

Repository documentation is scattered across cli/azd/docs/, AGENTS.md, and various READMEs with no consistent organization by purpose. Contributors and agents have no clear routing for where to find or place documentation.

New docs/ structure at repo root

• docs/concepts/ — Glossary, feature stages, alpha features
• docs/guides/ — Contributing, adding commands, creating extensions, observability
• docs/reference/ — Environment variables, azure.yaml schema, feature status table
• docs/architecture/ — System overview, command execution model, extension framework, provisioning pipeline, ADR template

docs/README.md serves as the index with a placement guide:

Content type	Location
Term or concept	docs/concepts/glossary.md
Contributor how-to	docs/guides/
Config reference	docs/reference/
System design or ADR	docs/architecture/
Implementation design	cli/azd/docs/design/

Copilot instructions

Added .github/instructions/documentation.instructions.md — tells Copilot when and where to update docs as code changes (new env vars, feature stage changes, new capabilities, etc.).

Design choices

• References, not duplication — new docs link to existing detailed docs in cli/azd/docs/ rather than copying content
• No file moves — existing docs stay in place; this is an additive organizational layer
• ADR-ready — docs/architecture/adr-template.md provides a lightweight template for future decision records

---

⌨️ Start Copilot coding agent tasks without leaving your editor — available in VS Code, Visual Studio, JetBrains IDEs and Eclipse.

[Copilot]

Pull request overview

Adds a structured root-level docs/ directory (concepts/guides/reference/architecture) plus Copilot documentation-maintenance instructions, and wires the new docs index from the root README to improve contributor navigation.

Changes:

• Introduces a new docs/README.md index and a set of new concept/guide/reference/architecture documents.
• Adds .github/instructions/documentation.instructions.md to guide agents/contributors on when/where to update documentation.
• Updates root README.md to link contributors to the new docs/ directory.

Reviewed changes

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

Show a summary per file

File	Description
docs/reference/feature-status.md	Adds a feature maturity reference table for commands/languages/hosts/etc.
docs/reference/environment-variables.md	Adds a consolidated environment variable reference (high-level) with pointer to implementation docs.
docs/reference/azure-yaml-schema.md	Adds a high-level azure.yaml schema overview and links to the machine-readable schema.
docs/guides/observability.md	Adds contributor guidance for tracing/telemetry and links to detailed docs.
docs/guides/creating-an-extension.md	Adds a step-by-step extension authoring guide and links to detailed docs.
docs/guides/contributing.md	Adds a contributor workflow guide (build/test/lint/checklist).
docs/guides/adding-a-new-command.md	Documents the ActionDescriptor pattern and command registration workflow.
docs/concepts/glossary.md	Adds a glossary of key terms used in the codebase.
docs/concepts/feature-stages.md	Defines alpha/beta/stable stages and links to feature status.
docs/concepts/alpha-features.md	Documents enabling/discovering alpha features and pointers to implementation details.
docs/architecture/system-overview.md	Adds a high-level architecture overview and directory map.
docs/architecture/provisioning-pipeline.md	Documents the provisioning pipeline and links to deeper design docs.
docs/architecture/extension-framework.md	Documents gRPC extension architecture and capabilities.
docs/architecture/command-execution-model.md	Documents command registration/build/middleware/action execution model.
docs/architecture/adr-template.md	Adds an ADR template for future architecture decisions.
docs/README.md	Adds the new docs landing page and “where do new docs go?” routing table.
README.md	Adds link to docs/README.md for contributor documentation.
.github/instructions/documentation.instructions.md	Adds Copilot instructions for ongoing documentation maintenance.

---

You can also share your feedback on Copilot code review. Take the survey.

[vhvb1989]

IIRC, we don't use a docs folder in the repo b/c there might be more than one product in the repo.
Are you hoping to move the docs for everything there?

We currently have /ext (for VSCode extension, gh-devcontainer, azdo-extension) and cli/azd for the cli+1st party extensions.

We might need to partition the folder into docs/<product>/README.md . But my preference would be to keep each's product docs within its own folder.

We currently have both a CLI and a go-library (for extensions) within cli/azd, and we also have .vscode folder inside cli/azd (as it was better to only open that folder for contributing to azd in the past, when the todo-templates were there).

I would consider a docs folder on the root to be some static-docs web which is published to the gh-pages of the repo, which is the common way to find public repos hosting their own docs. Did you consider that option?