[Draft] API Documentation Updates for v1.102.0

.claude/skills/openapi-overlay-generator/SKILL.md

@@ -60,10 +60,10 @@ info:
   version: 1.89
 actions:
   # ===== DATASETS - OPERATIONS =====
-  
+
   - target: "$.paths./datasets.get.summary"
     update: "List datasets"
-  
+
   - target: "$.paths./datasets.get.description"
     update: "Lists all datasets in a user context, enriched by `attributes`. Append `?workspaceId` to list datasets in a workspace context."
 ```
@@ -83,25 +83,91 @@ actions:
 - `offset`: "Number of results to skip for pagination. Default: `0`."
 - `max`: "Maximum number of results to return. Default: `{value}`."
 
-**Example**:
+**CRITICAL - Parameter Array Replacement Pattern**:
+
+When the comparison overlay contains a `remove: true` action followed by a parameter array `update`, you MUST preserve BOTH actions in your generated overlay:
+
+1. First action: Remove the entire existing parameters array with `remove: true`
+2. Second action: Replace with the complete new array including enriched descriptions
+
+**Why**: Simply updating individual parameter descriptions will cause duplicates and validation errors. The entire parameters array must be removed before replacement.
+
+**Example - Comparison overlay shows**:
+```yaml
+- target: $["paths"]["/data-links/{dataLinkId}/browse"]["get"]["parameters"][*]
+  remove: true
+- target: $["paths"]["/data-links/{dataLinkId}/browse"]["get"]["parameters"]
+  update:
+    - name: dataLinkId
+      in: path
+      description: Data-link string identifier
+      required: true
+      schema:
+        type: string
+    - name: path
+      in: query
+      description: Resource path to browse
+      # ... more params
+```
+
+**Your generated overlay MUST include BOTH actions**:
+```yaml
+overlay: 1.0.0
+info:
+  title: Data-links parameters overlay
+  version: 1.102.0
+actions:
+  # ===== DATA-LINKS PARAMETERS =====
+
+  # Remove entire parameters array to prevent duplicates
+  - target: "$.paths./data-links/{dataLinkId}/browse.get.parameters[*]"
+    remove: true
+
+  # Replace with complete array with enriched descriptions
+  - target: "$.paths./data-links/{dataLinkId}/browse.get.parameters"
+    update:
+      - name: dataLinkId
+        in: path
+        description: "Data-link string identifier."
+        required: true
+        schema:
+          type: string
+      - name: path
+        in: query
+        description: "Resource path to browse. Default: `/` (root directory)."
+        required: false
+        schema:
+          type: string
+      # ... include ALL parameters from comparison with enriched descriptions
+```
+
+**DO NOT do this** (updating descriptions without removal):
+```yaml
+# ❌ WRONG - This will create duplicate parameters and validation errors
+- target: "$.paths./data-links/{dataLinkId}/browse.get.parameters[?(@.name=='dataLinkId')].description"
+  update: "Data-link string identifier."
+# Missing the removal action = duplicates!
+```
+
+**Standard example** (when comparison shows simple description updates, not array replacement):
 ```yaml
 overlay: 1.0.0
 info:
   title: Datasets parameters overlay
   version: 1.89
 actions:
   # ===== DATASETS PARAMETERS =====
-  
+
   # ---- PATH PARAMETERS ----
-  
+
   - target: "$.paths./datasets/{datasetId}.get.parameters[?(@.name=='datasetId')].description"
     update: "Dataset numeric identifier."
-  
+
   # ---- QUERY PARAMETERS ----
-  
+
   - target: "$.paths./datasets.get.parameters[?(@.name=='workspaceId')].description"
     update: "Workspace numeric identifier."
-  
+
   - target: "$.paths./datasets.get.parameters[?(@.name=='max')].description"
     update: "Maximum number of results to return. Default: `20`."
 ```
@@ -125,13 +191,13 @@ info:
   version: 1.89
 actions:
   # ===== DATASETS SCHEMAS =====
-  
+
   - target: "$.components.schemas.DatasetRequest.properties.name"
     update:
       type: string
       required: true
       description: "Dataset name. Maximum 255 characters."
-  
+
   - target: "$.components.schemas.DatasetRequest.properties.description"
     update:
       type: string
@@ -170,6 +236,12 @@ Fix any errors or warnings before proceeding.
 
 ## Critical Rules
 
+### Overlay Files
+- ✅ NEVER create overlay files with empty actions lists
+- ❌ Do not create overlays with only comments and no actual update actions
+- ✅ If a feature area has no changes, omit the overlay file entirely
+- ❌ Empty overlays will break the workflow automation
+
 ### Summaries
 - ✅ Sentence case: "List datasets"
 - ❌ Title case: "List Datasets"
@@ -218,14 +290,14 @@ info:
   version: {version}
 actions:
   # ===== {FEATURE} - {TYPE} =====
-  
+
   # ---- {SECTION NAME} ----
-  
+
   - target: "$.paths.{endpoint}.{method}.{property}"
     update: "{value}"
-  
+
   # ---- {NEXT SECTION} ----
-  
+
   - target: "$.paths.{endpoint}.{method}.{property}"
     update: "{value}"
 ```
@@ -265,13 +337,41 @@ $.paths./datasets.get.responses['200'].description
 
 ## Generating Overlays from Comparison
 
+**CRITICAL - Preserve ALL Actions from Comparison Overlay**:
+
+Every single action defined in the comparison overlay MUST be preserved in your generated overlay files. No orphaned actions are allowed.
+
+**Requirements**:
+1. **One-to-one mapping**: For each action in the comparison overlay, there must be AT LEAST one corresponding action in the generated overlays
+2. **One-to-many mapping**: Some comparison actions will map to TWO generated actions:
+   - Comparison has `remove: true` followed by `update` → Generate BOTH removal and update actions
+   - Example: Parameter array replacement requires both remove and update
+3. **Verification**: Before finalizing, check that every action in the comparison overlay has a corresponding action in your generated overlays
+
+**Example**:
+```yaml
+# Comparison overlay has 2 actions:
+- target: $["paths"]["/endpoint"]["get"]["parameters"][*]
+  remove: true  # ← Action 1
+- target: $["paths"]["/endpoint"]["get"]["parameters"]
+  update: [...]  # ← Action 2
+
+# Your generated overlay MUST have both:
+- target: "$.paths./endpoint.get.parameters[*]"
+  remove: true  # ← Corresponds to Action 1
+- target: "$.paths./endpoint.get.parameters"
+  update: [...]  # ← Corresponds to Action 2
+```
+
 When analyzing a comparison overlay:
 
-1. **Identify new endpoints**: These need ALL three overlay types (operations, parameters, schemas)
-2. **Group by tag/controller**: Create one set of overlay files per resource (datasets, credentials, etc.)
-3. **Check for standard parameters**: Use exact standard descriptions
-4. **Follow patterns**: Use templates from overlay-patterns.md
-5. **Maintain consistency**: Same entities use same phrasing throughout
+1. **Count all actions**: Note the total number of actions in the comparison overlay
+2. **Identify new endpoints**: These need ALL three overlay types (operations, parameters, schemas)
+3. **Group by tag/controller**: Create one set of overlay files per resource (datasets, credentials, etc.)
+4. **Check for standard parameters**: Use exact standard descriptions
+5. **Follow patterns**: Use templates from overlay-patterns.md
+6. **Maintain consistency**: Same entities use same phrasing throughout
+7. **Verify completeness**: Ensure every comparison action is represented in your generated overlays
 
 ## Quality Checklist
 
@@ -316,13 +416,16 @@ Before finalizing overlay files:
 
 ## Common Mistakes to Avoid
 
-1. **Inconsistent parameter descriptions**: Always use standards.md exact wording
-2. **Missing periods in descriptions**: Descriptions are sentences
-3. **Title case summaries**: Use sentence case only
-4. **Invented terminology**: Use established terms only
-5. **Missing defaults**: Always specify default values in backticks
-6. **Incomplete enum listings**: List all accepted values
-7. **Vague descriptions**: Include specifics (max length, format, constraints)
+1. **Empty overlay files**: NEVER create overlay files with no action items (only comments). Empty overlays break the workflow automation.
+2. **Orphaned comparison actions**: EVERY action in the comparison overlay MUST have a corresponding action in your generated overlays. Check that nothing is missing.
+3. **Missing parameter array removal**: When comparison shows `remove: true` + array update, you MUST include BOTH actions. Updating descriptions without removal causes duplicate parameters and validation errors.
+4. **Inconsistent parameter descriptions**: Always use standards.md exact wording
+5. **Missing periods in descriptions**: Descriptions are sentences
+6. **Title case summaries**: Use sentence case only
+7. **Invented terminology**: Use established terms only
+8. **Missing defaults**: Always specify default values in backticks
+9. **Incomplete enum listings**: List all accepted values
+10. **Vague descriptions**: Include specifics (max length, format, constraints)
 
 ## Working with Permanent Overlays
 
@@ -353,4 +456,4 @@ After generating overlay files:
 6. **Regenerate**: Update MDX documentation files
 7. **Update sidebar**: Add new operation entries
 8. **Archive**: Move version-specific consolidated overlay file to overlay_archives/
-9. **Clean up**: Remove the old base spec, individual overlays, and other ephemeral files, leaving only the decorated spec, latest base spec, and `servers-overlay.yaml` in the specs folder. 
+9. **Clean up**: Remove the old base spec, individual overlays, and other ephemeral files, leaving only the decorated spec, latest base spec, and `servers-overlay.yaml` in the specs folder.

.claude/skills/openapi-overlay-generator/scripts/README.md

@@ -67,26 +67,43 @@ python scripts/check_consistency.py <overlay-file.yaml>
 
 ---
 
-### update_sidebar.py
+### update_sidebar_v2.py
 
-**Purpose**: Automatically adds new operation entries to the custom sidebar.js file.
+**Purpose**: Automatically adds new operation entries to the custom sidebar.js file with rename detection.
 
 **Usage**:
 ```bash
-python scripts/update_sidebar.py <sidebar.js> <analysis.json>
+# Basic usage - add new entries only
+python scripts/update_sidebar_v2.py <sidebar.js> <analysis.json>
+
+# Validate existing entries and detect renames
+python scripts/update_sidebar_v2.py <sidebar.js> <analysis.json> --validate
+
+# Auto-fix high-confidence renames (≥80% similarity)
+python scripts/update_sidebar_v2.py <sidebar.js> <analysis.json> --auto-fix-renames
 ```
 
 **What it does**:
 - Parses existing sidebar structure
 - Maps new endpoints to sidebar categories by tag
 - Generates properly formatted sidebar entries
+- **Validates existing doc IDs against generated .api.mdx files**
+- **Detects renamed files using fuzzy matching and pattern recognition**
+- **Recognizes common patterns** (e.g., `-1` → `-with-path` suffix changes)
 - Creates backup before modifying
 - Reports entries requiring manual intervention
 
 **Output**:
-- Updated sidebar.js with new operations
+- Updated sidebar.js with new operations and fixed renames
 - Backup file: sidebar.js.backup
-- Console report of changes made
+- Console report with validation results and suggestions
+
+**Rename Detection Features**:
+- Uses `difflib.SequenceMatcher` for similarity scoring
+- Pattern detection for common rename conventions
+- Shows top 3 suggestions with confidence scores
+- Auto-fix mode for high-confidence matches (≥80%)
+- Helps prevent broken sidebar links when doc IDs change
 
 ---
 
@@ -118,8 +135,10 @@ These scripts integrate into the automation workflow as follows:
 9. Docusaurus gen-api-docs
    → Generate MDX files
    ↓
-10. update_sidebar.py
+10. update_sidebar_v2.py
     → Add new entries to sidebar
+    → Validate existing entries
+    → Auto-fix renamed doc IDs
 ```
 
 ---
@@ -162,7 +181,7 @@ To add new validation rules to `check_consistency.py`:
 
 ### Extending Sidebar Mapping
 
-To add new tag-to-category mappings in `update_sidebar.py`:
+To add new tag-to-category mappings in `update_sidebar_v2.py`:
 
 Edit the `tag_to_category` dictionary in `map_tag_to_category()`:
 ```python
@@ -191,14 +210,24 @@ tag_to_category = {
 
 **Solution**: Copy the exact standard description from `references/standards.md`
 
-### update_sidebar.py can't find category
+### update_sidebar_v2.py can't find category
 
 **Cause**: New controller/tag not mapped to existing sidebar category
 
 **Solution**: Either:
 1. Add mapping in `map_tag_to_category()` function
 2. Manually create new category in sidebar.js
 
+### update_sidebar_v2.py reports missing doc IDs
+
+**Cause**: Doc IDs were renamed during API docs regeneration
+
+**Solution**:
+1. Run with `--validate` to see suggestions
+2. Review suggested renames and confidence scores
+3. Use `--auto-fix-renames` to apply high-confidence fixes (≥80%)
+4. Manually update sidebar for low-confidence matches
+
 ### extract-api-tables.mjs can't find spec
 
 **Cause**: Decorated spec not at expected location