diff --git a/api-docs/scripts/generate-openapi-articles.ts b/api-docs/scripts/generate-openapi-articles.ts
index aa1aea208..d53d4419f 100644
--- a/api-docs/scripts/generate-openapi-articles.ts
+++ b/api-docs/scripts/generate-openapi-articles.ts
@@ -6,16 +6,20 @@
  * for all InfluxDB products.
  *
  * This script:
- * 1. Runs getswagger.sh to fetch/bundle OpenAPI specs
- * 2. Copies specs to static directory for download
- * 3. Generates path group fragments (YAML and JSON)
- * 4. Creates article metadata (YAML and JSON)
- * 5. Generates Hugo content pages from article data
+ * 1. Cleans output directories (unless --no-clean)
+ * 2. Runs getswagger.sh to fetch/bundle OpenAPI specs
+ * 3. Copies specs to static directory for download
+ * 4. Generates path group fragments (YAML and JSON)
+ * 5. Creates article metadata (YAML and JSON)
+ * 6. Generates Hugo content pages from article data
  *
  * Usage:
- *   node generate-openapi-articles.js                    # Generate all products
- *   node generate-openapi-articles.js cloud-v2           # Generate single product
- *   node generate-openapi-articles.js cloud-v2 oss-v2    # Generate multiple products
+ *   node generate-openapi-articles.js                    # Clean and generate all products
+ *   node generate-openapi-articles.js cloud-v2           # Clean and generate single product
+ *   node generate-openapi-articles.js --no-clean         # Generate without cleaning
+ *   node generate-openapi-articles.js --dry-run          # Preview what would be cleaned
+ *   node generate-openapi-articles.js --skip-fetch       # Skip getswagger.sh fetch step
+ *   node generate-openapi-articles.js --validate-links   # Validate documentation links
  *
  * @module generate-openapi-articles
  */