sync-foundry-docs-after-release

# Sync Foundry docs after an ai-projects release Audit Microsoft Foundry docs against a released `@azure/ai-projects` package, sync explicit 2.x version guidance, and update affected JS/TS examples from SDK source. This workflow edits `azure-ai-docs-pr`, not SDK source or samples. ## When to use - A stable `@azure/ai-projects` version has been published. - Foundry articles still name an older 2.x JavaScript library version. - A release added, removed, renamed, or reshaped APIs used by Foundry JS/TS examples. - A post-release docs PR is needed in `azure-ai-docs-pr`. Do not use this skill to document an unreleased package, update other language tabs opportunistically, or migrate Foundry classic content from SDK 1.x. ## Inputs | Name | Default | Description | | ---------- | ---------------------------------------------------------------------- | ------------------------------------------------- | | `sdkRepo` | Current `azure-sdk-for-js` root | Repository containing `sdk/ai/ai-projects`. | | `docsRepo` | Explicit argument, `AZURE_AI_DOCS_PR`, then `~/repos/azure-ai-docs-pr` | Clean canonical checkout or verified GitHub fork. | | `version` | npm `latest` dist-tag | Stable published version to document. | Use [references/foundry-docs-surface.md](./references/foundry-docs-surface.md) as the maintained starting map. Always run a fresh search because docs move and new articles can acquire package references between releases. ## Safety rails - Stop if either repository has unrelated changes. Never stash, discard, or overwrite another contributor's work. - Stop if the target version, npm publication, release tag, tagged package metadata, and tagged dated changelog entry do not all identify the same stable version. The current branch can already contain the next unreleased version; in that case, use only the released tag snapshot as SDK evidence. - Work from a dedicated docs branch based on the latest canonical `MicrosoftDocs/azure-ai-docs-pr` `main`. Remote names are not fixed. - Read the docs repository's `.github/AGENTS.md`, `.github/copilot-instructions.md`, and applicable nested instructions before editing. - Do not edit `articles/foundry-classic/**` or its `1.0.1` references for a 2.x release. - Do not bulk-replace version numbers. API versions, model versions, Java/.NET package versions, Node versions, and REST dates are different domains. - Do not edit SDK files under `generated/` or published `samples/`. For JS evidence, use `src/`, `review/ai-projects-node.api.md`, `README.md`, `test/snippets.spec.ts`, and `samples-dev/`. - Do not invent examples. Every changed call, option, model, and return shape must be supported by the released API report and an SDK source/sample anchor. - Treat the docs snippet harness's `--dry-run` as syntax validation only. Prove SDK API compatibility separately against the exact released package. - Do not run live docs snippets or create Azure resources without explicit user approval. Static and compile-only validation comes first. - Do not stage, commit, push work, or open a docs PR unless the user requests it. The only preauthorized remote mutation is a non-force synchronization of a verified fork's `main` from canonical `main` during checkout preparation. ## Procedure Run SDK commands from the `azure-sdk-for-js` root and docs commands from the `azure-ai-docs-pr` root. ### 1. Resolve and inspect the docs checkout Resolve `docsRepo` in this order: 1. The path supplied by the user. 2. `$env:AZURE_AI_DOCS_PR`. 3. `Join-Path $HOME 'repos/azure-ai-docs-pr'`. Follow the inspection phase in [docs checkout and fork sync](./references/docs-checkout.md). Accept either: - A canonical checkout, where any remote points to `MicrosoftDocs/azure-ai-docs-pr`. - A checkout whose `origin` is verified through GitHub metadata as a fork of `MicrosoftDocs/azure-ai-docs-pr`. Record the canonical remote and optional fork remote by repository identity, not by assuming names such as `origin`, `upstream`, or `fork`. Also record the current branch, upstream, and both repository statuses: ```powershell git -C $docsRepo remote git -C $docsRepo branch --show-current git -C $docsRepo status --short git -C $sdkRepo status --short ``` Before editing, read: - `.github/AGENTS.md` - `.github/copilot-instructions.md` - Applicable files under `.github/instructions/` - `.github/skills/test-code-snippets/SKILL.md` - `.github/skills/learn-tabs/references/validation-checks.md` Preserve monikers, tab order, Markdown includes, `<!-- preserve -->` sections, and any generated-content boundaries those instructions identify. Do not switch or create a branch yet. Prove the release and build its API change ledger first, without changing either working tree. ### 2. Prove that the SDK version is released Follow [release verification](./references/release-verification.md). Require a stable npm `latest` version, matching exact npm publication, local release tag, tagged package version, and one dated tagged changelog entry. A package version or Git tag alone is not proof of publication. If the current SDK branch has moved to the next version, continue from the released tag snapshot. Never substitute newer unreleased APIs into this docs change. ### 3. Build the release change ledger Follow [release diff and evidence](./references/release-diff.md) to resolve the immediate stable predecessor and compare tagged package metadata, API report, source, README, snippets, and samples. Record any Node engine change. Create a short ledger before touching docs: - Added public operations, models, options, enum/union values, and properties. - Removed or renamed public symbols and their replacements. - Signature, requiredness, return-shape, paging, polling, and behavior changes. - New or updated SDK samples that demonstrate each customer-facing change. - Release changes that do not affect documentation snippets. Use this authority order when sources disagree. Read each source from `$releaseTag`, not from the current branch: 1. Released `review/ai-projects-node.api.md` and exported `src/` declarations. 2. Released `test/snippets.spec.ts`, `samples-dev/`, and README snippets. 3. The dated changelog entry for intent and customer impact. ### 4. Synchronize the fork and create the docs branch After release proof and ledger creation succeed, follow the preparation phase in [docs checkout and fork sync](./references/docs-checkout.md). If a verified fork exists, initiate `gh repo sync` for its `main` from `MicrosoftDocs/azure-ai-docs-pr` `main`, without `--force`, then fetch and require the fork and canonical remote-tracking refs to match. This covers both common layouts: `origin=canonical, fork=fork` and `origin=fork, upstream=canonical`. Create `docs/ai-projects-<version>` explicitly from canonical `main`, never from the currently checked-out feature branch. If the branch already exists, do not reset or recreate it; require it to contain the latest canonical `main` and no unrelated changes. ### 5. Inventory affected Foundry documentation Search the current docs tree instead of relying only on the reference map: ````powershell git -C $docsRepo grep -n -E ` '@azure/ai-projects|Azure AI Projects client library' -- ` articles/foundry articles/foundry-classic git -C $docsRepo grep -n -E '\b[0-9]+\.[0-9]+\.[0-9]+( or later)?\b' -- ` articles/foundry git -C $docsRepo grep -n -E '```(javascript|typescript|js|ts)|:::code' -- ` articles/foundry ```` For every removed, renamed, or materially changed API in the ledger, search its old and new symbol names under `articles/foundry/**`. Include shared Markdown includes and the source of every `:::code` directive. Before editing a shared include, find every caller by searching for its file name across both `articles/foundry/**` and `articles/foundry-classic/**`. If a classic article consumes it, do not put 2.x-only prose or code in that include; update the active caller or split the include according to docs-repo patterns. Classify each match before editing: | Match | Action | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | | Exact active 2.x SDK version in prose or a version matrix | Update to the released version. | | Minimum-version statement tied to a feature | Update only when that feature first appears in this release. | | Unpinned `npm install @azure/ai-projects` | Keep unpinned; verify it installs the current stable package. | | "latest" or "current version" guidance | Keep unless it is technically false; do not replace reflexively with a pin. | | Foundry classic `1.0.1` guidance | Leave unchanged. | | REST `api-version`, model version, Node version, or another language package version | Leave unchanged unless independently required by the release. | ### 6. Synchronize version guidance Update explicit active 2.x references from the prior SDK version to the released version. Keep installation commands unpinned unless the article deliberately teaches side-by-side version selection. In particular: - Update current-version matrices and sentences such as `Use Node.js 22 or later with @azure/ai-projects <version>`. - Update `<version> or later` only when it describes the general current SDK or a feature introduced by the release. - Do not change the Node requirement unless `package.json.engines.node` changed. - Update `ms.date` to the edit date in every modified published article/include. - Add `ai-usage: ai-assisted` to modified files under `articles/**` when it is absent and AI meaningfully contributed, as required by docs-repo guidance. ### 7. Update JavaScript and TypeScript snippets Audit every JS/TS snippet that uses an API in the release ledger. Cover: - Inline `javascript`, `typescript`, `js`, and `ts` fenced blocks. - JavaScript/TypeScript tabs inside Microsoft Learn tab groups or zone pivots. - Shared `[!INCLUDE]` files; edit the include source rather than every caller. - `:::code` directives; resolve and update the owning external sample instead of copying it into the article. For each affected example: 1. Start from the nearest released SDK sample or snippet source. 2. Match released method names, argument order, options-bag properties, model discriminators, async/paging/poller usage, and return shape. 3. Keep `DefaultAzureCredential`, environment variables, placeholders, and cleanup behavior consistent with docs-repo rules. 4. Update nearby prose and expected output when the observable behavior changed. 5. Preserve the surrounding language tabs exactly. Do not rewrite Python, .NET, Java, or REST examples merely to mirror JavaScript. If an external `:::code` source checkout is missing or the new API cannot be compiled or behavior-tested, stop that snippet update and report the owning repository/path as a follow-up. Do not publish an unverified approximation. ### 8. Validate the docs change First rerun searches for the prior version and every removed API symbol. Review each remaining hit and explain why it is intentionally retained. From `azure-ai-docs-pr`, validate the snippet environment and each changed article or include: ```powershell python .github/skills/test-code-snippets/scripts/test_snippets.py --check-env python .github/skills/test-code-snippets/scripts/test_snippets.py ` --doc <changed-article-or-include.md> --dry-run ``` `--dry-run` does not prove SDK API compatibility. Follow [snippet validation](./references/snippet-validation.md). For each complete changed JS/TS block, copy it unchanged to a scratch file outside both repositories and run the exact-version checker: ```powershell $snippetTester = Join-Path $packageDir ` '.github/skills/sync-foundry-docs-after-release/scripts/test-released-snippet.ps1' & $snippetTester -SnippetPath <scratch-snippet.ts> -Version $version ``` Then run the docs repository's tab-count, tab-ID-order, and stray-tab-anchor checks from `.github/skills/learn-tabs/references/validation-checks.md` against the changed files. Inspect VS Code Markdown diagnostics for broken links and metadata errors. Do not run the generic harness in non-dry mode across a mixed-language article without understanding its scope. `--live --confirm` requires explicit user approval because it can call Azure and create billable resources. Finally verify: - Every modified file belongs to the intended Foundry JS docs surface. - No `articles/foundry-classic/**` file changed. - No protected section or unrelated language tab changed. - No shared include introduced 2.x-only content into a classic caller. - Every explicit current 2.x reference equals the released version. - Every changed API call exists in the released API report. - `git diff --check` passes in `azure-ai-docs-pr`. ## Handoff Leave a focused working-tree diff in `azure-ai-docs-pr` and report: - Released and previous SDK versions/tags. - Version-reference files updated and intentionally retained matches. - JS/TS snippets updated, with their SDK source anchors. - External snippet follow-ups or validation gaps. - Exact validation commands and outcomes. If the user asks to publish, create a dedicated docs commit and preview pull request in `MicrosoftDocs/azure-ai-docs-pr` following that repository's branch, AI-disclosure, and Open Publishing requirements. For a fork checkout, push the work branch to the verified fork remote and target canonical `main`. Never force-push.