fix(metadata): preserve -- prefix in anchor IDs for CLI flags

src/generators/metadata/constants.mjs

@@ -7,9 +7,9 @@ export const DOC_API_SLUGS_REPLACEMENTS = [
   { from: /node.js/i, to: 'nodejs' }, // Replace Node.js
   { from: /&/, to: '-and-' }, // Replace &
   { from: /[/,:;\\ ]/g, to: '-' }, // Replace /,:;\. and whitespace
-  { from: /^-+(?!-*$)/g, to: '' }, // Remove any leading hyphens
+  { from: /^-(?=[^-])/g, to: '' }, // Remove a single leading hyphen (preserves -- prefix for CLI flags)
   { from: /(?<!^-*)-+$/g, to: '' }, // Remove any trailing hyphens
-  { from: /^(?!-+$).*?(--+)/g, to: '-' }, // Replace multiple hyphens
+  { from: /^(?!-+$)[^-].*?(--+)/g, to: '-' }, // Replace multiple consecutive hyphens (not at start)
 ];
 
 // These are regular expressions used to determine if a given Markdown heading

src/generators/metadata/utils/__tests__/slugger.test.mjs

@@ -51,8 +51,8 @@ describe('slug', () => {
       assert.strictEqual(slug('-foo', identity), 'foo');
     });
 
-    it('removes multiple leading hyphens', () => {
-      assert.strictEqual(slug('--foo', identity), 'foo');
+    it('preserves double leading hyphens (CLI flag prefix)', () => {
+      assert.strictEqual(slug('--foo', identity), '--foo');
     });
 
     it('preserves an all-hyphen string', () => {
@@ -80,6 +80,16 @@ describe('slug', () => {
     });
   });
 
+  describe('cli flag anchor preservation', () => {
+    it('preserves -- prefix for CLI flags', () => {
+      assert.strictEqual(slug('--permission', identity), '--permission');
+    });
+
+    it('preserves -- prefix for multi-word CLI flags', () => {
+      assert.strictEqual(slug('--allow-fs-read', identity), '--allow-fs-read');
+    });
+  });
+
   describe('integration with github-slugger', () => {
     it('lowercases and hyphenates a plain title', () => {
       assert.strictEqual(slug('Hello World'), 'hello-world');