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.

[jongio]

Reviewed 19 changed files. Found 3 issues (1 HIGH, 2 MEDIUM) not covered by existing feedback. Cross-references all valid. Feature status claims verified accurate. Table syntax issues from earlier Copilot bot comments appear fixed in later commits.

[hemarina]

@copilot Address all comment

[jongio]

Reviewed the latest commit (e90fc9c) which fixed my 3 previous findings. Found 5 new factual accuracy issues - capability names, method signatures, and completeness gaps that could mislead contributors.

[spboyer]

Docs restructuring is a welcome improvement. jongio's two review rounds caught the major factual issues (capability names, IoC pattern, hooks, Bind signature). Found 4 additional factual accuracy issues in files not yet covered by existing threads.

• command-execution-model.md:22 — actions.OutputFormat / actions.OutputFormatJson don't exist; actual types are output.Format / output.JsonFormat
• command-execution-model.md:60 — ActionResult description misrepresents the struct shape
• feature-status.md:7 — Missing 7+ commands from the canonical feature-stages table (init, auth, help, version, show, update, infra generate)
• alpha-features.md:49 — References a nonexistent "experiments section" in the changelog

[jongio]

Third round - checked files with no existing feedback. Found 3 more factual accuracy issues, same category as before (identifiers that don't match the codebase). 9 issues from my second review and spboyer's review are still unaddressed.

[Copilot]

Pull request overview

Adds a root-level docs/ hierarchy to centralize contributor/agent documentation and introduces Copilot instructions to keep documentation updated as the codebase evolves.

Changes:

• Introduces a new structured docs/ index and sub-sections (concepts/guides/reference/architecture) without moving existing cli/azd/docs/ content.
• Adds documentation maintenance instructions for Copilot at .github/instructions/documentation.instructions.md.
• Updates repo entry points (README + cspell overrides) to route contributors to the new documentation structure.

Reviewed changes

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

Show a summary per file

File	Description
docs/README.md	Adds a docs index + placement guide for where new documentation should live.
docs/concepts/glossary.md	Defines core terminology used across the azd codebase.
docs/concepts/feature-stages.md	Describes alpha/beta/stable definitions and graduation criteria.
docs/concepts/alpha-features.md	Documents how to enable/discover alpha features and CI env var patterns.
docs/guides/contributing.md	Adds contributor workflow guidance (build/test/lint/pre-commit).
docs/guides/adding-a-new-command.md	Documents the ActionDescriptor-based workflow for adding commands.
docs/guides/creating-an-extension.md	Provides an extension creation/publishing guide and links to detailed extension docs.
docs/guides/observability.md	Adds a tracing/telemetry guide and links to existing detailed docs.
docs/reference/environment-variables.md	Introduces a root-level entry point for env var documentation (with links to detailed reference).
docs/reference/azure-yaml-schema.md	Provides a high-level schema overview and links to JSON schema sources.
docs/reference/feature-status.md	Adds a simplified feature maturity table and links to the existing tracking table.
docs/architecture/system-overview.md	Summarizes azd system layout and key subsystems.
docs/architecture/command-execution-model.md	Documents command registration/execution pipeline concepts.
docs/architecture/extension-framework.md	Summarizes extension discovery/lifecycle/capabilities at a high level.
docs/architecture/provisioning-pipeline.md	Summarizes provisioning stages and links to detailed design docs.
docs/architecture/adr-template.md	Adds an ADR template for recording decisions.
.github/instructions/documentation.instructions.md	Adds Copilot guidance on when/where to update docs as code changes.
README.md	Updates contributor routing to point to root AGENTS.md and the new docs/ index.
.vscode/cspell.misc.yaml	Adds cspell overrides for new docs/ markdown content.

[jongio]

Three new factual accuracy issues not covered by existing feedback. Nine issues from prior rounds remain unaddressed.

[jongio]

Latest commit addresses most of my round 4 feedback, but the hook list change introduced a new issue. Two things:

1. infracreate/infradelete aren't valid hook names.
2. The preflight description in the glossary overstates server-side involvement.

Details inline.

[jongio]

Round 6 - checked the two latest commits. Hook list now matches knownHookNames in cmd/hooks.go:126-143 exactly, and the preflight description no longer overstates server-side involvement. All factual issues I raised across prior rounds look resolved. No new findings.