feat(azure.ai.docs): new extension -- unified agent-friendly docs front door

.github/CODEOWNERS

@@ -13,6 +13,7 @@
 # ── CLI extensions (AI) ──────────────────────────────────────────────────────
 /cli/azd/extensions/azure.ai.agents/        @JeffreyCA @trangevi @trrwilson @therealjohn
 /cli/azd/extensions/azure.ai.connections/   @JeffreyCA @trangevi @trrwilson @therealjohn
+/cli/azd/extensions/azure.ai.docs/          @JeffreyCA @trangevi @trrwilson @therealjohn
 /cli/azd/extensions/azure.ai.finetune/      @JeffreyCA @trangevi @achauhan-scc @kingernupur @saanikaguptamicrosoft
 /cli/azd/extensions/azure.ai.inspector/     @JeffreyCA @trangevi @trrwilson @therealjohn
 /cli/azd/extensions/azure.ai.models/        @JeffreyCA @trangevi @achauhan-scc @kingernupur @saanikaguptamicrosoft

.github/workflows/lint-ext-azure-ai-docs.yml

@@ -0,0 +1,22 @@
+name: ext-azure-ai-docs-ci
+
+on:
+  pull_request:
+    paths:
+      - "cli/azd/extensions/azure.ai.docs/**"
+      - ".github/workflows/lint-ext-azure-ai-docs.yml"
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  lint:
+    uses: ./.github/workflows/lint-go.yml
+    with:
+      working-directory: cli/azd/extensions/azure.ai.docs

cli/azd/extensions/azure.ai.docs/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Release History
+
+## 0.0.1-preview - Initial Version
+
+### Added
+
+* `azd ai doc skill` command group with topics for the Foundry skill
+  resource (`overview`, `manage`, `share`, `consume`). Covers the
+  `azure.ai.skills` extension lifecycle: the versioned skill model
+  (`default_version` / `latest_version`), the `azd ai skill` CLI
+  reference, cross-project sharing via download / re-upload, and
+  agent-side wiring (`skill_directories`) for Hosted agents.
+* `azd ai doc install` parent command group for embedded-pack
+  installers, hosting the renamed `install skill` child below.
+
+### Changed
+
+* Renamed `azd ai doc skills install` to `azd ai doc install skill`.
+  The new `install` parent groups embedded-pack installers; the `skill`
+  child copies the bundled `azd-ai-skill` coding-agent pack into the
+  user's project (the existing `--target` / `--path` / `--force` /
+  `--output` flag surface is unchanged). No backwards-compatible alias.
+* The embedded `SKILL.md` router now lists the Foundry skill resource
+  docs alongside agent / connection / toolbox docs and adds
+  `azd ai skill` to the `allowed-tools` list.

cli/azd/extensions/azure.ai.docs/README.md

@@ -0,0 +1,123 @@
+# Foundry docs for AI agents (Preview)
+
+Single front door for agent-friendly documentation across every
+`azure.ai.*` extension. The markdown is embedded in this extension --
+install once, and `azd ai doc <category> <topic>` returns documentation
+for any covered ai.* extension without requiring the sibling extension
+to be installed.
+
+The shape mirrors a familiar `skills` surface:
+
+```bash
+# Top-level index -- which ai.* extensions have docs
+azd ai doc
+
+# List topics for the agents extension
+azd ai doc agent
+
+# Print one topic's markdown
+azd ai doc agent initialize
+azd ai doc agent configure
+azd ai doc agent investigate
+azd ai doc agent operate
+
+# List topics for the Foundry skill resource (azure.ai.skills)
+azd ai doc skill
+azd ai doc skill overview
+azd ai doc skill manage
+azd ai doc skill share
+azd ai doc skill consume
+
+# List topics for Foundry routines (azure.ai.routines)
+azd ai doc routine
+azd ai doc routine overview
+azd ai doc routine triggers
+azd ai doc routine actions
+azd ai doc routine manage
+azd ai doc routine dispatch
+
+# Install the embedded azd-ai-skill coding-agent pack into the project
+azd ai doc install skill --target copilot
+```
+
+Each topic is a contract an agent reads to drive the matching CLI
+commands: exact invocations, JSON shape examples, error codes,
+confirmation-envelope handling.
+
+> Note: the `skill` doc category covers the **Foundry skill resource**
+> managed by the `azure.ai.skills` extension. It is intentionally
+> distinct from `install skill`, which copies the embedded
+> coding-agent pack (`azd-ai-skill`) into the user's project for tools
+> like Claude Code / GitHub Copilot.
+
+## Local development
+
+The first install in a new environment needs the full pack + publish +
+install flow because `azd x build` alone only deploys the binary to
+`~/.azd/extensions/<id>/` -- not the `extension.yaml` manifest. Without
+the manifest azd can't register the command surface, so `azd ai doc`
+will not appear under `azd ai`.
+
+```bash
+cd cli/azd/extensions/azure.ai.docs
+
+# First time only
+azd x build
+azd x pack
+azd x publish
+azd ext install azure.ai.docs
+
+# After that, iterate with watch (rebuilds + redeploys binary)
+azd x watch
+```
+
+## Adding topics for another ai.* extension
+
+The repo layout is intentionally simple:
+
+```
+internal/cmd/
+  skills/
+    agent/            <-- topics for azure.ai.agents
+      initialize.md
+      configure.md
+      investigate.md
+      operate.md
+    connection/       <-- topics for azure.ai.connections (today under azd ai agent connection)
+      overview.md
+      add.md
+      ...
+    toolbox/          <-- topics for azure.ai.toolboxes
+      overview.md
+      add.md
+      ...
+    skill/            <-- topics for azure.ai.skills (Foundry skill resource)
+      overview.md
+      manage.md
+      share.md
+      consume.md
+    routine/          <-- topics for azure.ai.routines (Foundry routine resource)
+      overview.md
+      triggers.md
+      actions.md
+      manage.md
+      dispatch.md
+  doc_catalog.go      <-- docCategories table (one entry per skills/ subdir)
+  doc_agent.go        <-- per-extension subcommand (one per category)
+  doc_connection.go
+  doc_toolbox.go
+  doc_skill.go
+  doc_routine.go
+```
+
+To add a new sibling:
+
+1. Drop `skills/<sibling>/<topic>.md` files into this extension.
+2. Add an entry to `docCategories` in `doc_catalog.go` (plus a
+   `categoryExtensionName` case in `doc_renderer.go`).
+3. Add a `new<Sibling>Command()` constructor mirroring `newSkillCommand()`
+   and register it (plus the matching `helpformat.Install` block) in
+   `root.go`.
+
+No coordination with the sibling extension is required; this extension is
+the source of truth for its agent-friendly docs.

cli/azd/extensions/azure.ai.docs/build.ps1

@@ -0,0 +1,78 @@
+# Ensure script fails on any error
+$ErrorActionPreference = 'Stop'
+
+# Get the directory of the script
+$EXTENSION_DIR = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# Change to the script directory
+Set-Location -Path $EXTENSION_DIR
+
+# Create a safe version of EXTENSION_ID replacing dots with dashes
+$EXTENSION_ID_SAFE = $env:EXTENSION_ID -replace '\.', '-'
+
+# Define output directory
+$OUTPUT_DIR = if ($env:OUTPUT_DIR) { $env:OUTPUT_DIR } else { Join-Path $EXTENSION_DIR "bin" }
+
+# Create output directory if it doesn't exist
+if (-not (Test-Path -Path $OUTPUT_DIR)) {
+    New-Item -ItemType Directory -Path $OUTPUT_DIR | Out-Null
+}
+
+# Get Git commit hash and build date
+$COMMIT = git rev-parse HEAD
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "Error: Failed to get git commit hash"
+    exit 1
+}
+$BUILD_DATE = (Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ")
+
+# List of OS and architecture combinations
+if ($env:EXTENSION_PLATFORM) {
+    $PLATFORMS = @($env:EXTENSION_PLATFORM)
+}
+else {
+    $PLATFORMS = @(
+        "windows/amd64",
+        "windows/arm64",
+        "darwin/amd64",
+        "darwin/arm64",
+        "linux/amd64",
+        "linux/arm64"
+    )
+}
+
+$APP_PATH = "$env:EXTENSION_ID/internal/cmd"
+
+# Loop through platforms and build
+foreach ($PLATFORM in $PLATFORMS) {
+    $OS, $ARCH = $PLATFORM -split '/'
+
+    $OUTPUT_NAME = Join-Path $OUTPUT_DIR "$EXTENSION_ID_SAFE-$OS-$ARCH"
+
+    if ($OS -eq "windows") {
+        $OUTPUT_NAME += ".exe"
+    }
+
+    Write-Host "Building for $OS/$ARCH..."
+
+    # Delete the output file if it already exists
+    if (Test-Path -Path $OUTPUT_NAME) {
+        Remove-Item -Path $OUTPUT_NAME -Force
+    }
+
+    # Set environment variables for Go build
+    $env:GOOS = $OS
+    $env:GOARCH = $ARCH
+
+    go build `
+        -ldflags="-X '$APP_PATH.Version=$env:EXTENSION_VERSION' -X '$APP_PATH.Commit=$COMMIT' -X '$APP_PATH.BuildDate=$BUILD_DATE'" `
+        -o $OUTPUT_NAME
+
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "An error occurred while building for $OS/$ARCH"
+        exit 1
+    }
+}
+
+Write-Host "Build completed successfully!"
+Write-Host "Binaries are located in the $OUTPUT_DIR directory."

cli/azd/extensions/azure.ai.docs/build.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+
+# Get the directory of the script
+EXTENSION_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Change to the script directory
+cd "$EXTENSION_DIR" || exit
+
+# Create a safe version of EXTENSION_ID replacing dots with dashes
+EXTENSION_ID_SAFE="${EXTENSION_ID//./-}"
+
+# Define output directory
+OUTPUT_DIR="${OUTPUT_DIR:-$EXTENSION_DIR/bin}"
+
+# Create output and target directories if they don't exist
+mkdir -p "$OUTPUT_DIR"
+
+# Get Git commit hash and build date
+COMMIT=$(git rev-parse HEAD)
+BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# List of OS and architecture combinations
+if [ -n "$EXTENSION_PLATFORM" ]; then
+    PLATFORMS=("$EXTENSION_PLATFORM")
+else
+    PLATFORMS=(
+        "windows/amd64"
+        "windows/arm64"
+        "darwin/amd64"
+        "darwin/arm64"
+        "linux/amd64"
+        "linux/arm64"
+    )
+fi
+
+APP_PATH="$EXTENSION_ID/internal/cmd"
+
+# Loop through platforms and build
+for PLATFORM in "${PLATFORMS[@]}"; do
+    OS=$(echo "$PLATFORM" | cut -d'/' -f1)
+    ARCH=$(echo "$PLATFORM" | cut -d'/' -f2)
+
+    OUTPUT_NAME="$OUTPUT_DIR/$EXTENSION_ID_SAFE-$OS-$ARCH"
+
+    if [ "$OS" = "windows" ]; then
+        OUTPUT_NAME+='.exe'
+    fi
+
+    echo "Building for $OS/$ARCH..."
+
+    # Delete the output file if it already exists
+    [ -f "$OUTPUT_NAME" ] && rm -f "$OUTPUT_NAME"
+
+    # Set environment variables for Go build
+    GOOS=$OS GOARCH=$ARCH go build \
+        -ldflags="-X '$APP_PATH.Version=$EXTENSION_VERSION' -X '$APP_PATH.Commit=$COMMIT' -X '$APP_PATH.BuildDate=$BUILD_DATE'" \
+        -o "$OUTPUT_NAME"
+
+    if [ $? -ne 0 ]; then
+        echo "An error occurred while building for $OS/$ARCH"
+        exit 1
+    fi
+done
+
+echo "Build completed successfully!"
+echo "Binaries are located in the $OUTPUT_DIR directory."