Document full extract filter surface and explicit exclude-all semantics (#103)

* docs: expand extract filter template fields and guidance

---------

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

Author: Copilot

src/templates/configs/filter-config.ts

@@ -47,7 +47,44 @@ export function generateFilterConfig(): string {
 #   - rate-limit-fragment
 #   - cors-fragment
 
-# Uncomment to extract ALL resources (default behavior if no filters specified)
-# Leave all sections commented to extract everything
+# Extract only specific gateways
+# gatewayNames:
+#   - default
+#   - internal-gateway
+
+# Extract only specific version sets
+# versionSetNames:
+#   - payments-v1
+
+# Extract only specific groups
+# groupNames:
+#   - administrators
+
+# Extract only specific subscriptions
+# subscriptionNames:
+#   - starter-subscription
+
+# Extract only specific schemas
+# schemaNames:
+#   - pet-schema
+
+# Extract only specific policy restrictions
+# policyRestrictionNames:
+#   - global-policy-restriction
+
+# Extract only specific documentations
+# documentationNames:
+#   - getting-started
+
+# Extract only specific workspaces
+# workspaceNames:
+#   - dev-workspace
+
+# Filter behavior:
+# - Leave a section commented out to include ALL resources of that type
+# - Set a section to an empty array ([]) to exclude ALL resources of that type
+#   Example:
+#   gatewayNames: []
+#   subscriptionNames: []
 `;
 }

tests/unit/templates/configs/config-templates.test.ts

@@ -40,6 +40,30 @@ describe('configs/filter-config', () => {
       expect(config).toContain('# policyFragmentNames:');
     });
 
+    it('should include commented examples for all supported filter fields', () => {
+      const config = generateFilterConfig();
+      const fields = [
+        'gatewayNames',
+        'versionSetNames',
+        'groupNames',
+        'subscriptionNames',
+        'schemaNames',
+        'policyRestrictionNames',
+        'documentationNames',
+        'workspaceNames',
+      ];
+      fields.forEach((field) => {
+        expect(config).toContain(`# ${field}:`);
+      });
+    });
+
+    it('should document empty arrays as exclude-all behavior', () => {
+      const config = generateFilterConfig();
+      expect(config).toContain('# - Set a section to an empty array ([]) to exclude ALL resources of that type');
+      expect(config).toContain('#   gatewayNames: []');
+      expect(config).toContain('#   subscriptionNames: []');
+    });
+
     it('should not have any uncommented configuration by default', () => {
       const config = generateFilterConfig();
       const lines = config.split('\n').filter((line) => line.trim() && !line.trim().startsWith('#'));