From ce96ecbdc6c1cca72748c86891e3ff49be95a831 Mon Sep 17 00:00:00 2001
From: Christopher Hiller <boneskull@boneskull.com>
Date: Mon, 2 Feb 2026 19:06:39 -0800
Subject: [PATCH] docs(typedoc): generate llms.txt

Uses [typedoc-plugin-llms-txt](https://npm.im/typedoc-plugin-llms-txt) to generate an `llms.txt`.
---
 .config/typedoc.js | 54 ++++++++++++++++++++++++++++++++++++++++++++++
 cspell.json        |  3 ++-
 package-lock.json  | 14 ++++++++++++
 package.json       |  1 +
 4 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/.config/typedoc.js b/.config/typedoc.js
index 7bc7193..cfa096b 100644
--- a/.config/typedoc.js
+++ b/.config/typedoc.js
@@ -58,6 +58,59 @@ export default {
     'TypeAlias',
   ],
   lightHighlightTheme: 'vitesse-light',
+  // llms.txt configuration
+  // llmsTxtDeclarations: Auto-generation doesn't work with kind-dir router
+  // for single-entry-point projects. Use empty array to disable.
+  // See: https://github.com/boneskull/typedoc-plugin-llms-txt
+  llmsTxtDeclarations: [],
+  llmsTxtHeader: {
+    description:
+      'A TypeScript-first CLI argument parser wrapping Node.js util.parseArgs() with full type inference and zero runtime dependencies.',
+    features: [
+      'Combinator-style fluent API: `bargs("app").globals(opts).command("cmd", pos, handler)`',
+      'Full type inference: options and positionals are strongly typed without manual annotations',
+      'Option builders: `opt.string()`, `opt.boolean()`, `opt.number()`, `opt.enum()`, `opt.array()`, `opt.count()`',
+      'Positional builders: `pos.string()`, `pos.number()`, `pos.enum()`, `pos.variadic()`',
+      'Transforms: `map()` to transform results, `merge()` to combine parsers, `camelCaseValues()` for key conversion',
+      'Built-in help generation with ANSI theming and terminal hyperlink support',
+      'Zero runtime dependencies - only wraps Node.js built-in util.parseArgs()',
+    ],
+  },
+  llmsTxtQuickReference: `// Simple CLI with options
+import { bargs, opt } from '@boneskull/bargs';
+
+const result = await bargs('greeter', { version: '1.0.0' })
+  .options(opt.options({
+    name: opt.string({ description: 'Name to greet', default: 'World' }),
+    excited: opt.boolean({ aliases: ['e'], description: 'Add excitement' }),
+  }))
+  .parseAsync();
+
+console.log(\`Hello, \${result.values.name}\${result.values.excited ? '!' : '.'}\`);
+
+// Command-based CLI with positionals
+import { bargs, opt, pos } from '@boneskull/bargs';
+
+await bargs('tasks', { version: '1.0.0' })
+  .globals(opt.options({
+    verbose: opt.boolean({ aliases: ['v'] }),
+  }))
+  .command('add', pos.positionals(
+    pos.string({ name: 'task', required: true }),
+  ), ({ positionals }) => console.log(\`Added: \${positionals[0]}\`))
+  .command('list', undefined, () => console.log('Listing tasks...'))
+  .parseAsync();
+
+// Type-safe enum options
+opt.enum({ values: ['debug', 'info', 'warn', 'error'], default: 'info' })
+
+// Variadic positionals (collects remaining args)
+pos.variadic({ name: 'files' })`,
+  llmsTxtSections: {
+    About: { displayName: 'About', order: 3 },
+    Guides: { displayName: 'Docs', order: 1 },
+    Reference: { displayName: 'Reference', order: 2 },
+  },
   markdownLinkExternal: true,
   name: 'BARGS',
   navigation: {
@@ -73,6 +126,7 @@ export default {
     'typedoc-plugin-mdn-links',
     'typedoc-plugin-extras',
     '@boneskull/typedoc-plugin-mermaid',
+    'typedoc-plugin-llms-txt',
   ],
   preserveWatchOutput: true,
   router: 'kind-dir',
diff --git a/cspell.json b/cspell.json
index 2cbe93e..e677e1b 100644
--- a/cspell.json
+++ b/cspell.json
@@ -73,6 +73,7 @@
     "subcommand",
     "subcommands",
     "navigations",
-    "dogg"
+    "dogg",
+    "llms"
   ]
 }
diff --git a/package-lock.json b/package-lock.json
index 843192b..ede3355 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -37,6 +37,7 @@
         "tsx": "4.21.0",
         "typedoc": "0.28.15",
         "typedoc-plugin-extras": "4.0.1",
+        "typedoc-plugin-llms-txt": "0.1.2",
         "typedoc-plugin-mdn-links": "5.0.10",
         "typescript": "5.9.3",
         "typescript-eslint": "8.50.0",
@@ -9331,6 +9332,19 @@
         "typedoc": "0.27.x || 0.28.x"
       }
     },
+    "node_modules/typedoc-plugin-llms-txt": {
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/typedoc-plugin-llms-txt/-/typedoc-plugin-llms-txt-0.1.2.tgz",
+      "integrity": "sha512-9q7x5ZdwkSZKJK23cvirtfQw87970n2p/hSv3T0YlOlgIY6isRHdUOM+QPErANFPXZv0X+ezS6QZp10dejOExQ==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "peerDependencies": {
+        "typedoc": "^0.28.0"
+      }
+    },
     "node_modules/typedoc-plugin-mdn-links": {
       "version": "5.0.10",
       "resolved": "https://registry.npmjs.org/typedoc-plugin-mdn-links/-/typedoc-plugin-mdn-links-5.0.10.tgz",
diff --git a/package.json b/package.json
index c864fe3..e156b47 100644
--- a/package.json
+++ b/package.json
@@ -106,6 +106,7 @@
     "tsx": "4.21.0",
     "typedoc": "0.28.15",
     "typedoc-plugin-extras": "4.0.1",
+    "typedoc-plugin-llms-txt": "0.1.2",
     "typedoc-plugin-mdn-links": "5.0.10",
     "typescript": "5.9.3",
     "typescript-eslint": "8.50.0",