Consolidate documentation into docs/ hub

.github/workflows/README.md

@@ -0,0 +1,84 @@
+# Agentic Workflows
+
+This directory contains [GitHub Agentic Workflows](https://github.github.com/gh-aw/introduction/overview/)
+(`gh-aw`) — LLM-powered GitHub Actions workflows that automate discovery and triaging of
+documentation and code quality gaps.
+
+## How gh-aw works
+
+Each workflow consists of two files:
+
+| File | Purpose |
+|------|---------|
+| `<name>.md` | Human-editable source: YAML front-matter (triggers, permissions, safe-outputs, tools) + Markdown prompt body |
+| `<name>.lock.yml` | Compiled GitHub Actions workflow generated from the `.md` by `gh aw compile`. **Do not edit by hand.** |
+
+The LLM prompt is the entire Markdown body of the `.md` file. It is loaded at runtime into the
+compiled workflow so only the `.md` needs editing to change agent behavior.
+
+## Workflows
+
+### `update-samples-and-docs`
+
+**Purpose:** On every push to `main`, detect documentation and sample gaps introduced by the
+commit, then file a focused GitHub issue with a detailed implementation guide. Copilot coding
+agent can be assigned to the issue to auto-implement the fix.
+
+**Flow:**
+1. Analyzes the push diff to find new/changed public APIs, types, or methods
+2. Scopes work to the changed `sdk/<service>/<package>/` directory using `ci.yml` package maps
+3. Checks `README.md` completeness against the canonical section structure
+4. Checks Java snippet markers (`// BEGIN: readme-sample-X` / `// END: readme-sample-X`) for orphans
+5. Files one GitHub issue with an `Implementation Guide` block
+6. Dispatches the issue-triage workflow to label and assign the issue
+
+**Safe outputs:** `create-issue` (max 1 per run), `noop` (if nothing to do)
+
+## Setup
+
+### Prerequisites
+
+- Install the [GitHub CLI](https://cli.github.com/)
+- Install the `gh-aw` extension:
+  ```bash
+  gh extension install github/gh-aw
+  ```
+
+### Required repository secrets
+
+Configure these in **Settings → Secrets and variables → Actions** for the repository:
+
+| Secret | Description |
+|--------|-------------|
+| `COPILOT_GITHUB_TOKEN` | GitHub token that has GitHub Copilot access (used to run the Copilot CLI agent) |
+| `GH_AW_GITHUB_TOKEN` | GitHub token used by the MCP server and safe-outputs processor (needs `issues:write`, `contents:read`) |
+
+### Compiling a workflow
+
+After editing an `.md` workflow definition, regenerate its lock file:
+
+```bash
+gh aw compile .github/workflows/update-samples-and-docs.md
+```
+
+Commit both the `.md` and the updated `.lock.yml` together.
+
+### Testing locally
+
+```bash
+# Validate the workflow definition without compiling
+gh aw validate .github/workflows/update-samples-and-docs.md
+
+# Dry-run the prompt rendering
+gh aw render .github/workflows/update-samples-and-docs.md
+```
+
+## Editing guidelines
+
+- Only edit the `.md` file — never edit `.lock.yml` by hand
+- After every edit, run `gh aw compile` and commit the new lock
+- Keep the prompt body focused: the agent reads everything between `---` fences as its system prompt
+- The `safe-outputs` section in the front-matter controls what the agent is allowed to produce
+  (creating issues, sending no-ops, etc.) — change it carefully
+- `permissions: read-all` at the top means the workflow itself has read-only access to the repo;
+  all write operations go through the safe-outputs MCP server which validates them

.github/workflows/update-samples-and-docs.lock.yml

@@ -0,0 +1,37 @@
+# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"PLACEHOLDER_RUN_GH_AW_COMPILE","compiler_version":"v0.67.1","strict":true,"agent_id":"copilot"}
+#    ___                   _   _
+#   / _ \                 | | (_)
+#  | |_| | __ _  ___ _ __ | |_ _  ___
+#  |  _  |/ _` |/ _ \ '_ \| __| |/ __|
+#  | | | | (_| |  __/ | | | |_| | (__
+#  \_| |_/\__, |\___|_| |_|\__|_|\___|
+#          __/ |
+#  _    _ |___/
+# | |  | |          / _| |
+# | |  | | ___ _ __ _  __| |_| | _____      ____
+# | |/\| |/ _ \ '__| |/ /|  _| |/ _ \ \ /\ / / __|
+# \  /\  / (_) | | | | ( | | | | (_) \ V  V /\__ \
+#  \/  \/ \___/|_| |_|\_\|_| |_|\___/ \_/\_/ |___/
+#
+# !! THIS LOCK FILE HAS NOT BEEN COMPILED YET !!
+#
+# To generate the compiled lock file, install the GitHub CLI agentic workflows
+# extension and run the following command from the repository root:
+#
+#   gh extension install github/gh-aw
+#   gh aw compile .github/workflows/update-samples-and-docs.md
+#
+# Then commit both this file and update-samples-and-docs.md together.
+#
+# For more information on gh-aw:
+#   https://github.github.com/gh-aw/introduction/overview/
+#
+# Documentation gap detector for the Azure SDK for Java repository.
+# Triggered on every push to main, analyzes diffs to identify documentation
+# gaps and files GitHub issues for Copilot coding agent to implement.
+#
+# Secrets required (configure in repository Settings → Secrets):
+#   - COPILOT_GITHUB_TOKEN   (GitHub token with Copilot access)
+#   - GH_AW_GITHUB_TOKEN     (token for MCP server / safe-outputs)
+#
+# See docs/contributor/agentic-workflows.md for setup instructions.

.github/workflows/update-samples-and-docs.md

@@ -0,0 +1,251 @@
+---
+description: |
+  Documentation gap detector for the Azure SDK for Java repository.
+  Triggered on every push to main, analyzes diffs to identify documentation
+  gaps and files GitHub issues for Copilot coding agent to implement.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: read-all
+
+network: defaults
+
+safe-outputs:
+  create-issue:
+    max: 1
+  noop:
+    report-as-issue: false
+  jobs:
+    dispatch_triage:
+      description: "Dispatch the issue triage workflow for the newly created issue"
+      runs-on: ubuntu-latest
+      needs: safe_outputs
+      output: "Triage workflow dispatched"
+      permissions:
+        actions: write
+        issues: write
+      steps:
+        - name: Dispatch triage workflow
+          uses: actions/github-script@v8
+          env:
+            CREATED_ISSUE_NUMBER: "${{ needs.safe_outputs.outputs.created_issue_number }}"
+          with:
+            script: |
+              const issueNumber = process.env.CREATED_ISSUE_NUMBER;
+
+              if (!issueNumber || issueNumber === '') {
+                core.info('No issue was created; skipping triage dispatch');
+                return;
+              }
+
+              const issueNum = parseInt(issueNumber, 10);
+              const repo = { owner: context.repo.owner, repo: context.repo.repo };
+
+              const { data: issue } = await github.rest.issues.get({ ...repo, issue_number: issueNum });
+              if (issue.labels && issue.labels.length > 0) {
+                await github.rest.issues.setLabels({ ...repo, issue_number: issueNum, labels: [] });
+                core.info(`Removed all labels from issue #${issueNum}`);
+              }
+
+              await github.rest.actions.createWorkflowDispatch({
+                ...repo,
+                workflow_id: 'issue-triage.lock.yml',
+                ref: 'main',
+                inputs: { issue_number: issueNumber }
+              });
+              core.info(`Dispatched triage for issue #${issueNum}`);
+
+tools:
+  web-fetch:
+  github:
+    toolsets: [issues, repos]
+
+timeout-minutes: 15
+---
+
+# Update Docs
+
+## Job Description
+
+<!-- After editing run 'gh aw compile' -->
+
+Your name is ${{ github.workflow }}. You are a **Documentation Gap Detector** for the GitHub repository `${{ github.repository }}`.
+
+### Mission
+
+Analyze code changes pushed to main, identify documentation gaps, and file a focused GitHub issue describing what needs updating so that Copilot coding agent can implement the changes.
+
+---
+
+### Workflow
+
+#### Step 1: Analyze the Push
+
+- Examine the diff for the triggering push to identify changed, added, or removed types, methods, classes, or APIs
+- Identify the commit author(s) and the PR number (if any) that triggered this push
+- Use package associations in `ci.yml` to map the changed artifact ID to its owning service directory
+  - `ci.yml` files live at `sdk/<serviceName>/ci.yml`; each lists the Maven artifacts `com.azure:<artifactId>` it owns
+- Limit scope to the same service directory and package as the changed code
+  - For example, if `sdk/storage/azure-storage-blob/src/` changed, only assess docs under `sdk/storage/azure-storage-blob/`
+
+#### Step 2: Assess Documentation
+
+- Check `sdk/<service>/<package>/README.md` for completeness against the canonical section structure (see Step 4)
+- Check for existing samples in `src/samples/java/` directories
+- Check for snippet-backed code in `ReadmeSamples.java` (or equivalent `*Samples.java` files) under `src/samples/java/`
+  - Java snippet markers: `// BEGIN: readme-sample-<name>` … `// END: readme-sample-<name>` in Java source
+  - Corresponding README fences: ` ```java readme-sample-<name> ``` `
+- Look for new public types, methods, or configuration that are not documented or sampled
+- Compare CHANGELOG entries against what the README describes
+- Assess whether the README follows the standard Java template (see Step 4)
+
+#### Step 3: Decide
+
+```
+IF no implementation code exists (empty repository):
+    - Use noop tool
+    - Exit
+
+IF no code changes require documentation updates:
+    - Use noop tool
+    - Exit
+
+IF all documentation is already up-to-date and comprehensive:
+    - Use noop tool
+    - Exit
+
+ELSE:
+    - Proceed to Step 4
+```
+
+#### Step 4: File a GitHub Issue
+
+Use the **create-issue** tool to file a single GitHub issue describing the documentation gap.
+
+- **Title:** `[<Service>] Docs: <concise description>`
+- **Body:** Follow the structure below exactly
+
+The issue body must follow this structure:
+
+```markdown
+## Documentation Gap
+
+**Package:** `com.azure:<artifactId>`
+**Service directory:** `sdk/<service>/<package>/`
+**Triggered by:** <commit SHA or PR #number> by @<author>
+
+## What Changed
+
+<Brief description of what was added/changed in the triggering push>
+
+## Gaps Found
+
+<Specific documentation gaps identified:>
+- <gap 1>
+- <gap 2>
+- <gap 3>
+
+<details>
+<summary><strong>📐 Implementation Guide</strong></summary>
+
+This section contains step-by-step instructions for a coding agent to implement the changes described above.
+
+### Step 1: Modify files
+
+For each file that needs changes, provide:
+- The absolute path from the repository root
+- Whether to create or edit the file
+- The exact content to add, replace, or remove — use fenced code blocks with the target language
+
+### Step 2: Add or update code snippets
+
+This repository uses a snippet extraction system where code in Java source files is linked into README documentation.
+The coding agent writes the code; the snippet markers keep README and source in sync. The flow is:
+
+1. **Write the sample code in a `ReadmeSamples.java`** (or `*Samples.java`) file under
+   `sdk/<service>/<package>/src/samples/java/<package_path>/`
+   - Wrap the code to be shown in the README with:
+     ```java
+     // BEGIN: readme-sample-<snippetName>
+     // ... code here ...
+     // END: readme-sample-<snippetName>
+     ```
+   - Any imports required by the snippet must appear at the top of the file
+   - Reference `sdk/storage/azure-storage-blob/src/samples/java/com/azure/storage/blob/ReadmeSamples.java`
+     as a canonical example
+
+2. **Add or update the snippet placeholder in the README** at the location where the code should appear:
+   ````
+   ```java readme-sample-<snippetName>
+   ... placeholder content (will be replaced) ...
+   ```
+   ````
+   The snippet content in the README is replaced automatically when the
+   `Update-Snippets` tooling runs in CI.
+
+3. For each snippet, provide:
+   - The Java source file path and the full method body including `// BEGIN:` / `// END:` tags
+   - The README section heading and surrounding context where the placeholder should appear
+   - The exact `<snippetName>` — this must match between the source file and the README fence
+
+### Step 3: Verify README structure
+
+The README at `sdk/<service>/<package>/README.md` must contain these sections in this order.
+List which sections are missing or incomplete and provide the content to add:
+
+1. **Getting started**
+   - Install the package (BOM snippet + direct dependency XML)
+   - Prerequisites
+   - Authenticate the client (`DefaultAzureCredential` example)
+2. **Key concepts**
+3. **Examples** (with `readme-sample-` backed code blocks)
+4. **Troubleshooting**
+5. **Next steps**
+6. **Contributing**
+
+Use `sdk/storage/azure-storage-blob/README.md` as the canonical reference for section formatting,
+Maven coordinate layout, BOM inclusion, and tone.
+
+### Step 4: Validate
+
+Run these commands in order. Each must succeed before proceeding to the next.
+
+1. `mvn compile -pl sdk/<service>/<package> -am -q` — verify code compiles
+2. `mvn test -pl sdk/<service>/<package> -Dsurefire.failIfNoSpecifiedTests=false -DskipLiveTests=true -q`
+   — verify unit tests pass
+3. Confirm that every `// BEGIN: readme-sample-X` tag in Java source has a matching
+   ` ```java readme-sample-X ``` ` fence in `README.md`, and vice-versa — no orphaned markers
+4. Confirm Maven coordinates in the README match the current `pom.xml` artifact version
+
+</details>
+
+## Next Steps
+
+> [!TIP]
+> **Ready for automated implementation?** Assign this issue to **@copilot** to have
+> Copilot coding agent implement the changes described in the Implementation Guide above.
+```
+
+#### Step 5: Dispatch Triage
+
+After the issue has been filed, use the `dispatch_triage` tool to trigger the issue triage workflow
+on the newly created issue.
+
+This dispatches full triage — including label prediction, CODEOWNERS owner lookup, and routing — on
+the created issue. The docs workflow does not apply labels or route to owners directly; triage handles that.
+
+---
+
+### Rules
+
+- Do NOT write code, create patches, or modify any files in the repository
+- Do NOT apply any labels to the issue — no labels of any kind; triage handles labeling
+- Do NOT assign the issue to anyone
+- File at most one issue per push; scope to the most impactful documentation gap
+- Title must start with `[<Service>] Docs:`
+- Always include the PR/commit author who triggered the push using @mention
+- If multiple packages changed in the same push, prioritize the one with the largest documentation gap
+- After creating the issue, always call `dispatch_triage` to trigger full triage