docs: correct default API version (#81)

* Initial plan

* Document supported CLI environment variables

* Align docs and comments with preview API version default

* Revert docs/commands/publish.md to main state

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: Copilot

docs/reference/configuration.md

@@ -39,7 +39,7 @@ Available on all commands (`extract`, `publish`, `init`):
 | `--cloud <name>` | Azure cloud environment | `public` |
 | `--log-level <level>` | Log verbosity: `debug`, `info`, `warn`, `error` | `info` |
 | `--format <format>` | Output format | `text` |
-| `--api-version <version>` | APIM REST API version | `2024-05-01` |
+| `--api-version <version>` | APIM REST API version | `2025-09-01-preview` |
 
 ### `apiops extract` Flags
 
@@ -86,7 +86,7 @@ Available on all commands (`extract`, `publish`, `init`):
 | `AZURE_CLIENT_ID` | all | Service principal client ID for authentication |
 | `AZURE_CLIENT_SECRET` | all | Service principal client secret for authentication |
 | `AZURE_TENANT_ID` | all | Microsoft Entra ID (Azure AD) tenant ID |
-| `AZURE_API_VERSION` | extract, publish | APIM REST API version (default: `2024-05-01`) |
+| `AZURE_API_VERSION` | extract, publish | APIM REST API version (default: `2025-09-01-preview`) |
 | `COMMIT_ID` | publish | Git commit SHA for incremental publish (alternative to `--commit-id`) |
 
 ### Authentication Environment Variables
@@ -149,7 +149,7 @@ backends:
 | Azure cloud | `public` | `--cloud` |
 | Log level | `info` | `--log-level` |
 | Output format | `text` | `--format` |
-| API version | `2024-05-01` | `--api-version` or `AZURE_API_VERSION` |
+| API version | `2025-09-01-preview` | `--api-version` or `AZURE_API_VERSION` |
 | Transitive deps | enabled | `--no-transitive` |
 | Dry run | disabled | `--dry-run` |
 | Delete unmatched | disabled | `--delete-unmatched` |

src/cli/extract-command.ts

@@ -77,9 +77,9 @@ async function executeExtract(
   }
 
   // Build service context
-  // Default to a recent preview API version so newer resource types (e.g.
-  // MCP-typed APIs) are returned by ARM list endpoints. Older versions
-  // (e.g. 2024-05-01) silently omit MCP APIs from /apis.
+  // Default to 2025-09-01-preview so newer resource types (e.g. MCP-typed
+  // APIs) are returned by ARM list endpoints. Older versions (e.g. 2024-05-01)
+  // can silently omit MCP APIs from /apis.
   const apiVersion = globalOpts.apiVersion ?? process.env.AZURE_API_VERSION ?? '2025-09-01-preview';
   const cloudName = globalOpts.cloud ?? 'public';
   const cloudConfig = getCloudConfig(cloudName);

src/cli/publish-command.ts

@@ -89,9 +89,9 @@ async function executePublish(
   }
 
   // Build service context
-  // Default to a recent preview API version so newer resource types (e.g.
-  // MCP-typed APIs) are accepted by ARM. Older versions (e.g. 2024-05-01)
-  // reject MCP API payloads.
+  // Default to 2025-09-01-preview so newer resource types (e.g. MCP-typed
+  // APIs) are accepted by ARM. Older versions (e.g. 2024-05-01) can reject
+  // MCP API payloads.
   const apiVersion =
     globalOpts.apiVersion ?? process.env.AZURE_API_VERSION ?? '2025-09-01-preview';
   const cloudName = globalOpts.cloud ?? 'public';