fix: address PR #102 reviewer feedback

- Add validation error when override YAML top-level is not a mapping
- Fix docs: add APIOps Toolkit hyperlink in environment-overrides guide
- Fix docs: note that gateway/subscription overrides are not supported
- Fix docs: rename overrides.prod.yaml → configuration.prod.yaml in
  getting-started.md and specs/quickstart.md for consistency"

Author: Copilot

docs/getting-started.md

@@ -76,7 +76,7 @@ Referenced backends, named values, and policy fragments are included automatical
 
 ## 4. Publish to a Target Environment
 
-Create `overrides.prod.yaml` for environment-specific values:
+Create `configuration.prod.yaml` for environment-specific values:
 
 ```yaml
 namedValues:
@@ -97,7 +97,7 @@ apiops publish \
   --resource-group prod-rg \
   --service-name prod-apim \
   --source ./apim-artifacts \
-  --overrides overrides.prod.yaml
+  --overrides configuration.prod.yaml
 ```
 
 ## 5. Preview Changes with Dry-Run

docs/guides/environment-overrides.md

@@ -25,9 +25,10 @@ apiops publish \
 
 ## Override file format (APIOps Toolkit-compatible)
 
-`apiops-cli` uses the APIOps Toolkit override layout:
+`apiops-cli` uses the [APIOps Toolkit](https://github.com/Azure/apiops) override layout:
 
 - Top-level resource sections: `namedValues`, `backends`, `apis`, `diagnostics`, `loggers`
+  > **Note:** Gateway and subscription overrides are not currently supported.
 - Each section is a list
 - Each list item contains `name` and `properties`
 

specs/quickstart.md

@@ -44,7 +44,7 @@ Referenced backends, named values, and policy fragments are included automatical
 
 ## Publish to a target environment
 
-Create `overrides.prod.yaml` for environment-specific values:
+Create `configuration.prod.yaml` for environment-specific values:
 
 ```yaml
 namedValues:
@@ -62,7 +62,7 @@ apiops publish \
   --resource-group prod-rg \
   --service-name prod-apim \
   --source ./apim-artifacts \
-  --overrides overrides.prod.yaml
+  --overrides configuration.prod.yaml
 ```
 
 ## Preview changes before publishing

src/lib/config-loader.ts

@@ -110,6 +110,12 @@ export async function loadOverrideConfig(filePath: string): Promise<OverrideConf
   try {
     const content = await fs.readFile(filePath, 'utf-8');
     const loaded = yaml.load(content);
+    if (loaded !== null && loaded !== undefined && !isPlainObject(loaded)) {
+      throw new Error(
+        `Override file at ${filePath} must be a YAML mapping (key: value pairs) at the top level, ` +
+        `but got ${Array.isArray(loaded) ? 'an array' : typeof loaded}.`
+      );
+    }
     const parsed = isPlainObject(loaded) ? loaded : {};
     const normalized = normalizeOverrideConfig(parsed);